chore: add local rust benchmark script (#14007)

Author: hardfist

package.json

@@ -38,6 +38,7 @@
     "build:binding:ci": "pnpm --filter @rspack/binding run build:ci",
     "build:binding:release": "pnpm --filter @rspack/binding run build:release",
     "build:binding:profiling": "pnpm --filter @rspack/binding run build:profiling",
+    "build:bench": "cargo codspeed build -m simulation --profile codspeed -p rspack_benchmark",
     "prepare": "is-ci || husky",
     "test:hot": "pnpm --filter \"@rspack/*\" test:hot",
     "test:unit": "pnpm --parallel --filter \"@rspack/*\" test",
@@ -48,6 +49,7 @@
     "test:rs": "cargo test --workspace --exclude rspack_binding_api --exclude rspack_node --exclude rspack_binding_builder --exclude rspack_binding_builder_macros --exclude rspack_binding_builder_testing --exclude rspack_binding_build --exclude rspack_napi --exclude rspack_watcher -- --nocapture",
     "bench:ci": "pnpm run bench:prepare && pnpm run bench:rust && pnpm --filter bench run bench",
     "bench:rust": "RSPACK_BENCHCASES_DIR=$PWD/.bench/rspack-benchcases cargo codspeed run",
+    "bench:rust:local": "mkdir -p /tmp/rspack-codspeed-valgrind-tmp && TMPDIR=/tmp/rspack-codspeed-valgrind-tmp RAYON_NUM_THREADS=1 RSPACK_BENCHCASES_DIR=$PWD/.bench/rspack-benchcases codspeed run -m simulation -- cargo codspeed run -m simulation",
     "bench:prepare": "node ./scripts/bench/setup.mjs"
   },
   "engines": {

website/docs/en/contribute/development/project.md

@@ -214,9 +214,17 @@ End-to-end tests for Rspack, covering real-world scenarios and integration testi
 - **`fixtures/`**: Shared fixtures and utilities for E2E tests
 - **`utils/`**: Utility functions for E2E test execution
 
-### Benchmarks (`bench/`)
+### JavaScript benchmarks (`bench/`)
 
 Performance benchmarks for tracking Rspack JavaScript API performance and preventing performance degradation:
 
 - **`fixtures/`**: Benchmark test fixtures (e.g., `ts-react` project for benchmarking)
 - Benchmark files for measuring build performance and API execution time
+
+### Rust benchmarks (`xtask/benchmark/`)
+
+CodSpeed benchmarks for tracking Rust compilation pipeline performance:
+
+- **`cases/`**: End-to-end benchmark cases for module graph, chunk graph, bundling, scanning dependencies, and persistent cache
+- **`stages/`**: Focused benchmark cases for individual compilation stages
+- See **`xtask/benchmark/README.md`** for local CodSpeed CPU simulation commands and Valgrind temporary file locations

website/docs/zh/contribute/development/project.md

@@ -214,9 +214,17 @@ Rspack 的端到端测试，涵盖真实场景和集成测试：
 - **`fixtures/`**: E2E 测试的共享 fixtures 和工具
 - **`utils/`**: E2E 测试执行的工具函数
 
-### 基准测试 (`bench/`)
+### JavaScript 基准测试 (`bench/`)
 
 用于跟踪 Rspack JavaScript API 性能并防止性能退化的性能基准测试：
 
 - **`fixtures/`**: 基准测试 fixtures（例如，用于基准测试的 `ts-react` 项目）
 - 用于测量构建性能和 API 执行时间的基准测试文件
+
+### Rust 基准测试 (`xtask/benchmark/`)
+
+用于跟踪 Rust 编译流水线性能的 CodSpeed 基准测试：
+
+- **`cases/`**: 针对 module graph、chunk graph、bundling、依赖扫描和 persistent cache 的端到端基准测试用例
+- **`stages/`**: 针对单个 compilation stage 的基准测试用例
+- 请参考 **`xtask/benchmark/README.md`** 了解本地 CodSpeed CPU simulation 命令和 Valgrind 临时文件位置

website/project-words.txt

@@ -94,7 +94,6 @@ memfs
 mimalloc
 minifiers
 miro
-MPHF
 modulegeneratorassetdataurl
 modulegeneratorassetdataurlencoding
 modulegeneratorassetdataurlmimetype
@@ -111,6 +110,7 @@ moduleparsercssauto
 moduleparsercssautonamedexports
 moduleparsercssmodule
 monaco
+MPHF
 msvc
 myorg
 myrspackapp
@@ -214,10 +214,11 @@ webpack
 xcode
 xcrun
 xctrace
-xmcp
 Xeon
 XKKCNZZNJD
+xmcp
 xstyled
+xtask
 xxhash
 yannik
 Zack

xtask/benchmark/README.md

@@ -0,0 +1,89 @@
+# Rspack Rust benchmarks
+
+Rust benchmark cases live in `xtask/benchmark/cases` and `xtask/benchmark/stages`.
+
+## Prepare benchmark fixtures
+
+Some benchmark cases use fixtures from `.bench/rspack-benchcases`. Prepare them before running the full benchmark suite or any bundle-related case:
+
+```bash
+pnpm run bench:prepare
+```
+
+## Run in CI mode
+
+The CI command runs `cargo codspeed run` directly:
+
+```bash
+pnpm run bench:rust
+```
+
+When this command is run outside a CodSpeed runner environment, `cargo-codspeed` may only check benchmarks and print `Checked:` entries instead of making CPU simulation measurements.
+
+## Build benchmark binaries
+
+Use the build helper to run the same CodSpeed build command used by CI:
+
+```bash
+npm run build:bench
+```
+
+The script expands to:
+
+```bash
+cargo codspeed build -m simulation --profile codspeed -p rspack_benchmark
+```
+
+This only builds the benchmark binaries for CodSpeed simulation mode. It does not execute measurements.
+
+## Run local CPU simulation measurements
+
+Use the local helper script to run benchmarks through the CodSpeed runner in CPU simulation mode:
+
+```bash
+npm run bench:rust:local
+```
+
+Pass a benchmark name filter after `--` to run a single benchmark:
+
+```bash
+npm run bench:rust:local -- build_chunk_graph
+```
+
+The script expands to:
+
+```bash
+mkdir -p /tmp/rspack-codspeed-valgrind-tmp && TMPDIR=/tmp/rspack-codspeed-valgrind-tmp RAYON_NUM_THREADS=1 RSPACK_BENCHCASES_DIR=$PWD/.bench/rspack-benchcases codspeed run -m simulation -- cargo codspeed run -m simulation
+```
+
+This command:
+
+- Creates a stable temporary directory for CodSpeed and Valgrind files
+- Sets `TMPDIR` so the temporary files are written to that directory
+- Sets `RAYON_NUM_THREADS=1` to match the single-threaded CI simulation environment
+- Sets `RSPACK_BENCHCASES_DIR` to the prepared benchmark fixtures
+- Wraps `cargo codspeed run -m simulation` in `codspeed run -m simulation` so local runs use the CodSpeed runner environment instead of only checking benchmarks
+
+A real local simulation run prints `Measured:` entries. The script sets `TMPDIR` to `/tmp/rspack-codspeed-valgrind-tmp`, so CodSpeed and Valgrind temporary files are easy to inspect:
+
+```bash
+find /tmp/rspack-codspeed-valgrind-tmp -maxdepth 3 -type f
+```
+
+Typical files include `profile.*.out/valgrind.log`, `profile.*.out/runner.log`, and `vgdb-pipe-*` files.
+
+## Requirements
+
+Local CPU simulation requires:
+
+- `cargo-codspeed`
+- `codspeed`
+- CodSpeed's Valgrind build
+
+Check the installed tools with:
+
+```bash
+cargo codspeed --version
+codspeed --version
+valgrind --version
+```