docs: improve guide for setup and building (rolldown#536)

### Description  ### Test Plan  ---
Ailmendra17Stictime · Mar 10, 2024 · 0c1d04f · 0c1d04f
1 parent ca56e02
commit 0c1d04f
Show file tree

Hide file tree

Showing 6 changed files with 109 additions and 70 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -39,16 +39,16 @@ jobs:
       - if: steps.filter.outputs.src == 'true'
         run: cargo deny check
 
-  rust-lint:
-    name: Rust Lint
+  rust-validation:
+    name: Rust Validation
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - name: Install Rust
         uses: moonrepo/setup-rust@v1
         with:
-          bins: just
+          bins: just, taplo-cli
           cache-base: main
           components: clippy,rustfmt
 

diff --git a/README.md b/README.md
@@ -26,12 +26,12 @@ The Rolldown project is heavily inspired by:
 
 - [Rollup](https://github.com/rollup/rollup), created by [Rich Harris](https://github.com/Rich-Harris) and maintained by [Lukas Taegert-Atkinson](https://github.com/lukastaegert).
 - [esbuild](https://github.com/evanw/esbuild), created by [Evan Wallace](https://github.com/evanw).
-- [@parcel/sourcemap](https://github.com/parcel-bundler/source-map).
 
 And supported by:
 
 - [napi-rs](https://github.com/napi-rs/napi-rs) for Node.js add-ons in Rust via Node-API.
 - [oxc](https://github.com/oxc-project/oxc) for the underlying parser and resolver.
+- [@parcel/sourcemap](https://github.com/parcel-bundler/source-map).
 
 # Licenses
 

diff --git a/justfile b/justfile
@@ -4,27 +4,36 @@ set shell := ["bash", "-cu"]
 _default:
     just --list -u
 
-ready:
-  git diff --exit-code --quiet
-  just fmt
-  just check
-  just test
-  just lint
-  git status
+# `smoke` command almost run all ci checks locally. It's useful to run this before pushing your changes.
+smoke:
+    just smoke-rust
+    just smoke-node
 
-# INITIALIZE
+smoke-rust:
+    just check-rust
+    just test-rust
+    just lint-rust
 
-init-rust:
-    cargo binstall rusty-hook taplo-cli cargo-insta cargo-deny -y
+smoke-node:
+    just check-node
+    just test-node
+    just lint-node
 
-init-node:
-    yarn install
 
+# Initialize the project and its submodules
 init:
     just init-rust
     just init-node
     git submodule update --init
 
+init-rust:
+    cargo binstall taplo-cli cargo-insta cargo-deny -y
+
+init-node:
+    yarn install
+
+
+
 # Update our local branch with the remote branch (this is for you to sync the submodules)
 update:
     git pull
@@ -42,7 +51,10 @@ check:
     just check-rust
     just check-node
 
-# TESTING
+# run tests for both Rust and Node.js
+test:
+    just test-rust
+    just test-node
 
 test-rust:
     cargo test --no-fail-fast
@@ -51,54 +63,33 @@ test-node:
     yarn build:node
     yarn test
 
-test:
-    just test-rust
-    just test-node
-
-# FORMATTING
-
+# Fix formatting issues both for Rust and Node.js.
+fmt:
+    just fmt-rust
+    just fmt-lint
+
 fmt-rust:
     cargo fmt --all -- --emit=files
+    taplo fmt
 
 fmt-lint:
     yarn prettier
 
-fmt:
-    just fmt-rust
-    just fmt-lint
-    taplo format
-
-# LINTING
+# lint the codebase
+lint:
+    just lint-rust
+    just lint-node
 
 lint-rust:
-    cargo clippy --workspace --all-targets -- --deny warnings
     cargo fmt --all -- --check
+    taplo fmt --check
+    cargo clippy --workspace --all-targets -- --deny warnings
 
 lint-node:
     yarn lint-filename
     yarn lint-code
     yarn prettier:ci
 
-lint:
-    just lint-rust
-    just lint-node
-    taplo format
-
-# smoke commands allow you to run checks locally without pushing branches to the remote
-smoke-rust:
-    just check-rust
-    just test-rust
-    just lint-rust
-
-smoke-node:
-    just check-node
-    just test-node
-    just lint-node
-
-smoke:
-    just smoke-rust
-    just smoke-node
-
 # BENCHING
 
 setup-bench:

diff --git a/package.json b/package.json
@@ -3,6 +3,10 @@
   "version": "0.0.5",
   "description": "Rollup in Rust",
   "private": true,
+  "packageManager": "yarn@4.1.1",
+  "engines": {
+    "node": ">=18.18.0"
+  },
   "workspaces": [
     "crates/rolldown_binding",
     "crates/rolldown_binding_wasm",
@@ -57,9 +61,5 @@
     "singleQuote": true,
     "trailingComma": "all",
     "arrowParens": "always"
-  },
-  "packageManager": "yarn@4.1.1",
-  "engines": {
-    "node": ">=18.18.0"
   }
 }
diff --git a/web/docs/contrib-guide/build.md b/web/docs/contrib-guide/build.md
@@ -1,10 +1,44 @@
-# Building Bindings
+# Building
 
-For the NAPI-RS based Node packages to work, and for their tests and benchmarks to run, they must be built first. This is done by running `yarn build` in the root directory. This will spin up a process that builds the Node/WASM binding crates (with Cargo), and then builds the rolldown npm package. The `yarn build` script is also smart enough to only re-build if it detects changes since the last time it was run.
+Rolldown is built on Rust and Node.js, so and building process includes building Rust crates, Node.js packages and the glue part that binds them together. The glue part is also a Node.js package, but building it will also trigger building the Rust crates.
+
+Luckily, NAPI-RS has encapsulated the process of building the glue part, we don't need to worry about the details.
+
+Typically, rolldown has two main packages:
+
+- `@rolldown/node`, which is the final npm package that users will install directly.
+- `@rolldown/node-binding`, which is the glue part that binds Rust and Node.js together.
+
+## Incremental Build
+
+For the NAPI-RS based Node packages to work, and for their tests and benchmarks to run, they must be built first. This is done by running `yarn build` in the root directory. This will spin up a process that builds the Node/WASM binding crates (with Cargo), and then builds the rolldown npm package.
+
+The `yarn build` script is also smart enough to only re-build if it detects changes since the last time it was run.
 
 `yarn build` accepts two flags:
 
 - `--no-wasm`
 - `--release` (**important if running benchmarks**)
 
 In addition, the `yarn watch` script can be used to watch the file system for changes, and re-build the bindings and npm package when changes are detected (using the same process as `yarn build`). This is useful for development when you're constantly making changes and re-running tests.
+
+## Fresh Build
+
+If you want to force a fresh build on `@rolldown/node`, you can run `yarn build:node`. It will topologically run the `build` command in `@rolldown/node` and `@rolldown/node-binding` package.
+
+To build some specific package only:
+
+For `@rolldown/node`, you could run:
+
+- `yarn workspace @rolldown/node build`.
+
+For `@rolldown/node-binding`, you could run:
+
+- `yarn workspace @rolldown/node-binding build`
+- `yarn workspace @rolldown/node-binding build:release` (**important if running benchmarks**)
+
+:::warning
+
+Due to the boundary between Rust and Node.js, once you changed the Rust code, you need to rebuild the `@rolldown/node-binding` package to see the changes while executing in Node.js.
+
+:::
diff --git a/web/docs/contrib-guide/setup.md b/web/docs/contrib-guide/setup.md
@@ -3,7 +3,7 @@
 ## Prerequisites
 
 - Rust >= 1.75
-- Node.js >= v18
+- Node.js >= 18.18.0
 - Yarn >= 4
 - Git
 
@@ -15,6 +15,8 @@ On your first checkout of the repository, you'll need to install required tools
 If you are using [proto](https://moonrepo.dev/proto), you can run `proto use` in the repository root to install Rust, Node.js, and Yarn. For other tools, or if not using proto, continue reading.
 :::
 
+We have made initializing the project automatic with the `just` command. However, you still need to install some meta tools and dependencies before you can use the command.
+
 ### Rust
 
 Rolldown is built on Rust and requires `rustup` and `cargo` to exist in your environment. You can
@@ -27,39 +29,51 @@ cargo install cargo-binstall
 cargo binstall just
 ```
 
-Once installed, run the following to install secondary tools.
-
-```shell
-just init-rust  # Run this command in the directory where the `rolldown` project located
-```
-
 ### Node.js
 
 Rolldown is a npm package built with [NAPI-RS](https://napi.rs/) and is published to the npm registry, and as such requires Node.js and Yarn (for dependency management).
 
-We recommend installing Node.js with a version manager, like [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm). Make sure to install and use Node.js version 18+, which is the minimum requirement for this project. You can skip this step if you are already using a Node.js version manager of your choice and on a Node.js version that meets the requirement.
+We recommend installing Node.js with a version manager, like [nvm](https://github.com/nvm-sh/nvm) or [fnm](https://github.com/Schniz/fnm). Make sure to install and use Node.js version 18.18.0+, which is the minimum requirement for this project. You can skip this step if you are already using a Node.js version manager of your choice and on a Node.js version that meets the requirement.
 
 We recommend enabling Yarn via [corepack](https://nodejs.org/api/corepack.html), so the correct version of Yarn can be automatically used when working in this project:
 
 ```shell
 corepack enable
 ```
 
-Once both Node.js and Yarn are configured, run the following to install dependencies.
+### Init
+
+Once Rust, Node.js and Yarn are installed, run the following command to install all required dependencies:
 
 ```shell
-just init-node
+just init
 ```
 
+After initialization, everything should be set up and ready to go. You could run
+
+```shell
+just smoke
+```
+
+to verify that everything is set up correctly.
+
+::: tip
+`just smoke` command almost run all ci checks locally. It's useful to run this before pushing your changes. It also has two variants `just smoke-rust` and `just smoke-node` to run only Rust or Node.js checks.
+:::
+
 ## High Level Workflow
 
 The following commands are available and should be used in your standard development workflow.
 
 - `just init` - Install required tools and dependencies.
-- `just check` - Runs the type checker.
-- `just lint` - Lints code.
-- `just fmt` - Formats code.
+- `just smoke` - Runs various kinds of checks to ensure the project is in a good state.
+- `just lint` - Lint the codebase.
+- `just fmt` - Fix formatting issues.
+- `just check` - Run the type checker.
 - `just test` - Runs tests. Also see [Testing](./test.md).
-- `just ready` - Run everything!
 
 > Every command will run both Rust and Node.js scripts. To only target one, append `-rust` or `-node` to the just command. For example, `just lint-rust` or `just fmt-node`.
+
+::: tip
+You could run the command `just` only and it will show you all available commands.
+:::