Profiling with rustc-perf

The Rust benchmark suite provides a comprehensive way of profiling and benchmarking the Rust compiler. You can find instructions on how to use the suite in its manual.

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.

You can use the ./x perf -- <command> [options] command to use this integration.

Note that you need to specify arguments after -- in the x perf command! You will not be able to pass arguments without the double dashes.

You can use normal bootstrap flags for this command, such as --stage 1 or --stage 2, for example to modify the stage of the created sysroot. It might also be useful to configure config.toml to better support profiling, e.g. set rust.debuginfo-level = 1 to add source line information to the built compiler.

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 ids.
  • 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 sampling profiler.
  • cachegrind: Use Cachegrind to generate a detailed simulated trace of the compiler's execution.

You can find a more detailed description of the profilers in the rustc-perf manual.

You can use the following options for the x perf command, which mirror the corresponding options of the profile_local and bench_local commands that you can use in the suite:

  • --include: Select benchmarks which should be profiled/benchmarked.
  • --profiles: Select profiles (Check, Debug, Opt, Doc) which should be profiled/benchmarked.
  • --scenarios: Select scenarios (Full, IncrFull, IncrPatched, IncrUnchanged) which should be profiled/benchmarked.