user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

sembr src/profiling/with_rustc_perf.md

Browse source
This commit is contained in:
Tshepang Mbambo 2026-01-12 22:15:18 +02:00
parent d442a793b2
commit 328942672d
1 changed files with 14 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

22
src/doc/rustc-dev-guide/src/profiling/with_rustc_perf.md
View file

@ -1,9 +1,11 @@
# Profiling with rustc-perf
The [Rust benchmark suite][rustc-perf] provides a comprehensive way of profiling and benchmarking
the Rust compiler. You can find instructions on how to use the suite in its [manual][rustc-perf-readme].
the Rust compiler.
You can find instructions on how to use the suite in its [manual][rustc-perf-readme].
However, using the suite manually can be a bit cumbersome. To make this easier for `rustc` contributors,
However, using the suite manually can be a bit cumbersome.
To make this easier for `rustc` contributors,
the compiler build system (`bootstrap`) also provides built-in integration with the benchmarking suite,
which will download and build the suite for you, build a local compiler toolchain and let you profile it using a simplified command-line interface.
@ -14,8 +16,9 @@ You can use normal bootstrap flags for this command, such as `--stage 1` or `--s
`x perf` currently supports the following commands:
- `benchmark <id>`: Benchmark the compiler and store the results under the passed `id`.
- `compare <baseline> <modified>`: Compare the benchmark results of two compilers with the two passed `id`s.
- `eprintln`: Just run the compiler and capture its `stderr` output. Note that the compiler normally does not print
anything to `stderr`, you might want to add some `eprintln!` calls to get any output.
- `eprintln`: Just run the compiler and capture its `stderr` output.
Note that the compiler normally does not print
anything to `stderr`, you might want to add some `eprintln!` calls to get any output.
- `samply`: Profile the compiler using the [samply][samply] sampling profiler.
- `cachegrind`: Use [Cachegrind][cachegrind] to generate a detailed simulated trace of the compiler's execution.
@ -29,15 +32,18 @@ You can use the following options for the `x perf` command, which mirror the cor
- `--scenarios`: Select scenarios (`Full`, `IncrFull`, `IncrPatched`, `IncrUnchanged`) which should be profiled/benchmarked.
## Example profiling diff for external crates
It can be of interest to generate a local diff for two commits of the compiler for external crates.
It can be of interest to generate a local diff for two commits of the compiler for external crates.
To start, in the `rustc-perf` repo, build the collector, which runs the Rust compiler benchmarks as follows.
```
cargo build --release -p collector
```
The collector can then be run using cargo, specifying the collector binary. It expects the following arguments:
- `<PROFILE>`: Profiler selection for how performance should be measured. For this example we will use Cachegrind.
The collector can then be run using cargo, specifying the collector binary.
It expects the following arguments:
- `<PROFILE>`: Profiler selection for how performance should be measured.
For this example we will use Cachegrind.
- `<RUSTC>`: The Rust compiler revision to benchmark, specified as a commit SHA from `rust-lang/rust`.
Optional arguments allow running profiles and scenarios as described above. More information regarding the mandatory and
Optional arguments allow running profiles and scenarios as described above.
More information regarding the mandatory and
optional arguments can be found in the [rustc-perf-readme-profilers].
Then, for the case of generating a profile diff for the crate `serve_derive-1.0.136`, for two commits `<SHA1>` and `<SHA2>` from the `rust-lang/rust` repository,