swc-project/swc
1
1
Fork 0
mirror of https://github.com/swc-project/swc.git synced 2024-08-16 11:50:22 +03:00
Code Issues Actions 4 Packages Projects Releases Wiki Activity

chore: Update markdown files to use "SWC" instead of "swc" (#2744)

Browse Source
This commit is contained in:
Tim Neutkens 2021-11-15 05:26:04 +01:00 committed by GitHub
parent 8df860e16c
commit 3ebc5c6b69
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 81 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
ARCHITECTURE.md
View File

@ -1,53 +1,54 @@
# swc architecture
# SWC architecture
This document gives a high level overview of swc internals. You may find it useful if you want to contribute to swc or if you are interested in the inner workings of swc.
This document gives a high level overview of SWC internals. You may find it useful if you want to contribute to SWC or if you are interested in the inner workings of SWC.
## Macros
See [blog post about swc macros](https://swc.rs/blog/2020/01/04/pmutil#macros-built-with-pmutil).
<!-- TODO: fix link -->
<!-- See [blog post about SWC macros](https://swc.rs/blog/2020/01/04/pmutil#macros-built-with-pmutil). -->
swc uses proc macro extensively to reduce work. Please see links below to know what each macro do.
SWC uses proc macro extensively to reduce work. Please see links below to know what each macro do.
- [enum_kind][]
- [string_enum][]
- [ast_node][]
- [enum_kind][]
- [string_enum][]
- [ast_node][]
And some adhoc-macros are used.
- [parser_macros][]
- [codegen_macros][]
- [parser_macros][]
- [codegen_macros][]
These macro breaks macro hygiene.
## Structure
### `/atoms`
### [`/crates/swc_atoms`](crates/swc_atoms)
Handle string interning for the swc project. The crate depends on [string_cache](https://github.com/servo/string-cache) from servo.
Handle string interning for the SWC project. The crate depends on [string_cache](https://github.com/servo/string-cache) from servo.
### `/common`
### [`/crates/swc_common`](crates/swc_common)
Contains code related to span, hygiene and error reporting.
Also, it contains / re-exports codes for visitor pattern. `Visit<T>` is non-mutating visitor, while `Fold<T>` is a mutating visitor.
### `/ecmascript/ast`
### [`/crates/swc_ecma_ast`](crates/swc_ecma_ast)
Contains ast nodes for javascript and typescript.
Contains AST nodes for javascript and typescript.
### `/ecmascript/codegen`
### [`/crates/swc_ecma_codegen`](crates/swc_ecma_codegen)
Converts javascript ast into javascript code.
Converts javascript AST into javascript code.
### `/ecmascript/parser`
### [`/crates/swc_ecma_parser`](crates/swc_ecma_parser)
Parses javascript and typescript
### `/ecmascript/transforms`
### [`/crates/swc_ecma_transforms_base`](crates/swc_ecma_transforms_base)
Theres are three core transforms named `resolver`, `hygiene`, `fixer`. Other transforms depends on them.
#### `/ecmascript/transforms/src/resolver`
#### [`/crates/swc_ecma_transforms_base/src/resolver`](crates/swc_ecma_transforms_base/src/resolver)
This pass resolves and marks all identifiers in the file.
@ -56,7 +57,7 @@ e.g.
```js
let a = 1;
{
let a = 1;
let a = 1;
}
```
@ -71,7 +72,7 @@ let a#0 = 1;
where number after `#` denotes the hygiene id. If two identifiers have same symbol but different hygiene id, it's different.
#### `/ecmascript/transforms/src/hygiene`
#### [`/crates/swc_ecma_transforms_base/src/hygiene`](crates/swc_ecma_transforms_base/src/hygiene)
Hygiene pass actually changes symbol of identifiers with same symbol but different hygiene id.
@ -87,13 +88,13 @@ becomes
```js
let a = 1;
{
let a1 = 2;
let a1 = 2;
}
```
#### `/ecmascript/transforms/src/fixer`
#### [`/crates/swc_ecma_transforms_base/src/fixer`](crates/swc_ecma_transforms_base/src/fixer)
Fixes borken ast. This allow us to simply fold types like `BinExpr` without caring about operator precedence.
Fixes broken AST. This allow us to simply fold types like `BinExpr` without caring about operator precedence.
It means,
@ -105,7 +106,7 @@ let v = BinExpr {
};
```
(other passes generates ast like this)
(other passes generates AST like this)
is converted into
@ -123,9 +124,10 @@ and printed as
(1 + 2) * 3;
```
#### `/ecmascript/transforms/src/compat`
<!-- TODO: add correct references to files -->
<!-- #### `/ecmascript/transforms/src/compat`
Contains codes related to converting new generation javascript codes for old browsers.
Contains code related to converting new generation javascript codes for old browsers.
#### `/ecmascript/transforms/src/modules`
@ -133,15 +135,15 @@ Contains code related to transforming es6 modules to other modules.
#### `/ecmascript/transforms/src/optimization`
Contains code related to making code faster on runtime. Currently only small set of optimization is implemented.
Contains code related to making code faster on runtime. Currently only small set of optimization is implemented. -->
## Tests
swc uses [official ecmascript conformance test suite called test262][test262] for testing.
SWC uses the [official ecmascript conformance test suite called test262][test262] for testing.
Parser tests ensures that parsed result of test262/pass is identical with test262/pass-explicit.
Parser tests ensures that parsed result of `test262/pass` is identical with `test262/pass-explicit`.
Codegen tests ensures that generated code is equivalent to goldened reference files located at [tests/references](ecmascript/codegen/tests/references).
Codegen tests ensures that generated code is equivalent to golden fixture files located at [tests/references](crates/swc_ecma_codegen/tests).
[enum_kind]: https://rustdoc.swc.rs/enum_kind/derive.Kind.html
[string_enum]: https://rustdoc.swc.rs/string_enum/derive.StringEnum.html

67
CONTRIBUTING.md
View File

@ -1,6 +1,10 @@
# Contributing to swc
# Contributing to SWC
Thank you for your interest in contributing to swc! Good places to start are this document, ARCHITECTURE.md, which describes the high-level structure of swc and E-easy bugs on the issue tracker.
Thank you for your interest in contributing to SWC! Good places to start are:
- Reading this document
- Reading the high-level structure of SWC in [ARCHITECTURE.md](ARCHITECTURE.md)
- [E-easy][e-easy] labeled issues on the [issue tracker][issue-tracker]
## Code of Conduct
@ -8,30 +12,15 @@ All contributors are expected to follow our [Code of Conduct].
## Bug reports
We can't fix what we don't know about, so please report problems liberally. This
We can't fix what we don't know about, so please report problems. This
includes problems with understanding the documentation, unhelpful error messages,
and unexpected behavior.
Opening an issue is as easy as following [this link][new-issues] and filling out
the fields. Here's a template that you can use to file an issue, though it's not
necessary to use it exactly:
<short summary of the problem>
I tried this: <minimal example that causes the problem>
I expected to see this happen: <explanation>
Instead, this happened: <explanation>
I'm using <output of `swc --version`>
All three components are important: what you did, what you expected, what
happened instead. Please use https://gist.github.com/ if your examples run long.
You can open a new issue by following [this link][new-issues] and choosing one of the issue templates.
## Feature requests
Please feel free to open an issue or to send a pr.
Please feel free to open an issue using the [feature request template][new-issues].
## Working on issues
@ -40,8 +29,8 @@ If you're looking for somewhere to start, check out the [E-easy][e-easy] and
Feel free to ask for guidelines on how to tackle a problem on [gitter][] or open a
[new issue][new-issues]. This is especially important if you want to add new
features to swc or make large changes to the already existing code-base.
swc's core developers will do their best to provide help.
features to SWC or make large changes to the already existing code-base.
The SWC core developers will do their best to provide help.
If you start working on an already-filed issue, post a comment on this issue to
let people know that somebody is working it. Feel free to ask for comments if
@ -50,30 +39,29 @@ you are unsure about the solution you would like to submit.
We use the "fork and pull" model [described here][development-models], where
contributors push changes to their personal fork and create pull requests to
bring those changes into the source repository. This process is partly
automated: Pull requests are made against swc's master-branch, tested and
automated: Pull requests are made against SWC's repository, tested and
reviewed. Once a change is approved to be merged, a friendly bot merges the
changes into an internal branch, runs the full test-suite on that branch
and only then merges into master. This ensures that swc's master branch
passes the test-suite at all times.
and only then merges into master. This ensures that SWC passes the test-suite at all times.
Your basic steps to get going:
Steps to get started:
- Fork swc and create a branch from master for the issue you are working on.
- Fork SWC and create a branch from master for the issue you are working on.
- Make sure you have the `make` utility installed, along with Rust and C/C++
compilers.
- Please adhere to the code style that you see around the location you are
working on.
- [Commit as you go][githelp].
- Include tests that cover all non-trivial code. The existing tests
in `test/` provide templates on how to test swc's behavior in a
in `test/` provide templates on how to test SWC's behavior in a
sandbox-environment. The internal crate `testing` provides a vast amount
of helpers to minimize boilerplate. See [`testing/lib.rs`] for an
introduction to writing tests.
- Make sure `cargo test` passes.
- Run `cargo test` and make sure that it passes.
- All code changes are expected to comply with the formatting suggested by `rustfmt`.
You can use `rustup component add --toolchain nightly rustfmt-preview` to install `rustfmt` and use
`rustfmt +nightly --unstable-features --skip-children` on the changed files to automatically format your code.
- Push your commits to GitHub and create a pull request against swc's `master` branch.
- Push your commits to GitHub and create a pull request against the `swc-project/swc` `master` branch.
## Getting your development environment set up
@ -111,12 +99,12 @@ After cloning the project there are a few steps required to get the project runn
## Pull requests
After the pull request is made, one of the swc project developers will review your code.
After the pull request is made, one of the SWC project developers will review your code.
The review-process will make sure that the proposed changes are sound.
Please give the assigned reviewer sufficient time, especially during weekends.
If you don't get a reply, you may poke the core developers on [gitter].
If you don't get a reply, you may ping the core developers on [gitter].
A merge of swc's master-branch and your changes is immediately queued
A merge of SWC's master-branch and your changes is immediately queued
to be tested after the pull request is made. In case unforeseen
problems are discovered during this step (e.g. a failure on a platform you
originally did not develop on), you may ask for guidance. Push additional
@ -128,11 +116,13 @@ the code was previously reviewed. Large or tricky changes may require several
passes of review and changes.
Once the reviewer approves your pull request, a friendly bot picks it up
and merges it into swc's `master` branch.
and merges it into the SWC `master` branch.
## Contributing to the documentation
TODO
The SWC documentation can be found at [`swc-project/website`](https://github.com/swc-project/website/tree/master/pages/docs).
At the bottom of each page on [swc.rs](https://swc.rs) there is a `Edit this page on GitHub` button that immediately links to the right page to edit.
## Issue Triage
@ -145,7 +135,7 @@ still valid. Load up an older issue, double check that it's still true, and
leave a comment letting us know if it is or is not. The [least recently
updated sort][lru] is good for finding issues like this.
Contributors with sufficient permissions on the Rust-repository can help by
Contributors with sufficient permissions on the SWC repository can help by
adding labels to triage issues:
- Yellow, **A**-prefixed labels state which **area** of the project an issue
@ -158,7 +148,7 @@ adding labels to triage issues:
an issue is **C-feature-request**, but is not **Feature accepted**,
then it was not thoroughly discussed, and might need some additional design
or perhaps should be implemented as an external subcommand first. Ping
@swc-projcet/swc if you want to send a PR for an such issue.
`@swc-project/swc` if you want to send a PR for an such issue.
- Green, **E**-prefixed labels explain the level of **experience** or
**effort** necessary to fix the issue. [**E-mentor**][e-mentor] issues also
@ -171,7 +161,7 @@ adding labels to triage issues:
- Light orange, **L**-prefixed labels indicate language related to the bug.
[gist]: https://gist.github.com/
[new-issues]: https://github.com/swc-project/swc/issues/new
[new-issues]: https://github.com/swc-project/swc/issues/new/choose
[e-easy]: https://github.com/swc-project/swc/labels/E-easy
[e-mentor]: https://github.com/swc-project/swc/labels/E-mentor
[code of conduct]: https://www.rust-lang.org/conduct.html
@ -179,3 +169,4 @@ adding labels to triage issues:
[`testing/lib.rs`]: https://github.com/swc-project/swc/blob/master/testing/src/lib.rs
[irlo]: https://internals.rust-lang.org/
[subcommands]: https://doc.rust-lang.org/cargo/reference/external-tools.html#custom-subcommands
[issue-tracker]: https://github.com/swc-project/swc/issues

8
README.md
View File

@ -22,9 +22,9 @@
</a>
</p>
swc (stands for `speedy web compiler`) is a super-fast typescript / javascript compiler written in rust. It's a library for rust and javascript at the same time. If you are using swc from rust, see [rustdoc](https://rustdoc.swc.rs/swc/) and for most users, your entrypoint for using library will be [parser](https://rustdoc.swc.rs/swc_ecma_parser/).
SWC (stands for `Speedy Web Compiler`) is a super-fast TypeScript / JavaScript compiler written in Rust. It's a library for Rust and JavaScript at the same time. If you are using SWC from Rust, see [rustdoc](https://rustdoc.swc.rs/swc/) and for most users, your entry point for using the library will be [parser](https://rustdoc.swc.rs/swc_ecma_parser/).
If you are using swc from javascript, please refer to [docs on the website](https://swc.rs/docs/installation/).
If you are using SWC from JavaScript, please refer to [docs on the website](https://swc.rs/docs/installation/).
# Documentation
@ -55,7 +55,7 @@ Please see [benchmark results](https://swc.rs/docs/benchmark-transform) on the w
</a>
</p>
swc is a community-driven project, and is maintained by a group of [volunteers](https://opencollective.com/swc#team). If you'd like to help support the future of the project, please consider:
SWC is a community-driven project, and is maintained by a group of [volunteers](https://opencollective.com/swc#team). If you'd like to help support the future of the project, please consider:
- Giving developer time on the project. (Message us on [Discord](https://discord.gg/GnHbXTdZz6) (preferred) or [Github discussions](https://github.com/swc-project/swc/discussions) for guidance!)
- Giving funds by becoming a sponsor (see https://opencollective.com/swc)!
@ -67,7 +67,7 @@ documentation useful ([ARCHITECTURE.md](ARCHITECTURE.md)).
## License
swc is primarily distributed under the terms of both the MIT license
SWC is primarily distributed under the terms of both the MIT license
and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT for details.

3
crates/swc_babel_compat/README.md
View File

@ -1,6 +1,7 @@
Convert swc AST to Babel AST.
Convert SWC AST to Babel AST.
## Testing
To run tests
```bash

7
crates/swc_babel_compat/tests/README.md
View File

@ -1,5 +1,6 @@
## How tests work
The babel-compat tests are mostly written as fixtures, similar to the [@babel/parser tests](https://github.com/babel/babel/tree/main/packages/babel-parser/test/fixtures). The `src/convert.rs` test runner looks in the `fixtures/` directory for input and expected output files. Input files are parsed into an swc AST and converted to a Babel AST in Rust. Output files are parsed directly into a Babel AST. The two ASTs are then compared, with any differences causing the test to fail.
The babel-compat tests are mostly written as fixtures, similar to the [@babel/parser tests](https://github.com/babel/babel/tree/main/packages/babel-parser/test/fixtures). The `src/convert.rs` test runner looks in the `fixtures/` directory for input and expected output files. Input files are parsed into an SWC AST and converted to a Babel AST in Rust. Output files are parsed directly into a Babel AST. The two ASTs are then compared, with any differences causing the test to fail.
## How to write a test
@ -24,6 +25,6 @@ node babelgen.js fixtures/my-test/input.js > fixtures/my-test/output.json
This happens a lot with `None` and `Some(false)`. You'll probably want to add a normalizer function to the Normalizer visitor in `src/normalize/mod.rs`.
## Other random utlities
- `swcgen.js`: Prints the swc AST as JSON.
- `compare.sh`: prints the Babel and swc ASTs side-by-side.
- `swcgen.js`: Prints the SWC AST as JSON.
- `compare.sh`: prints the Babel and SWC ASTs side-by-side.

12
crates/swc_bundler/README.md
View File

@ -1,13 +1,13 @@
# swc_bundler
Bundler for the swc project.
Bundler for the SWC project.
## Features
- Clean merging (generated code is easy to optimize)
- Parallel file loading
- Tree shaking
- Common js support (aka `require`)
- Circular imports
- Clean merging (generated code is easy to optimize)
- Parallel file loading
- Tree shaking
- Common js support (aka `require`)
- Circular imports
Tests live at `/spack`.

2
crates/swc_css_parser/README.md
View File

@ -1,6 +1,6 @@
# swc_css_parser
CSS parser for [the swc project](https://swc.rs)
CSS parser for [the SWC project](https://swc.rs)
# Structure

2
crates/swc_ecma_minifier/README.md
View File

@ -1,6 +1,6 @@
# Minifier
EcmaScript minifier for the swc project. This is basically a port of terser.
EcmaScript minifier for the SWC project. This is basically a port of terser.
# Note

2
crates/swc_plugin/README.md
View File

@ -1,3 +1,3 @@
# swc_plugin
Base runtime for swc plugins, written in rust.
Base runtime for SWC plugins, written in rust.