Skip to content

Document profiling rustc with Valgrind and Cachegrind - #3073

Closed
isHeSatoshi wants to merge 1 commit into
rust-lang:mainfrom
isHeSatoshi:document-valgrind-cachegrind
Closed

isHeSatoshi wants to merge 1 commit into
rust-lang:mainfrom
isHeSatoshi:document-valgrind-cachegrind

Conversation

@isHeSatoshi

@isHeSatoshi isHeSatoshi commented Oct 19, 2026 •

Copy link
Copy Markdown

Fixes #1166.

The profiling chapter lists perf, Tracy and WPA, but nothing about Valgrind. Callgrind and Cachegrind measure something the sampling profilers do not: exact instruction counts, and simulated cache and branch behaviour.

The part worth writing down is not how to run Valgrind, it is how to get it to profile the compiler, which is the caveat the issue points at. There are two traps:

  • cargo runs rustc as a subprocess, so valgrind cargo build profiles cargo. Valgrind has to be the parent of rustc.
  • The rustc in PATH is usually the rustup shim, not the compiler, so you would profile the shim.

The page covers both, plus the fact that RUSTC names a program rather than a command line, and the two ways to slot Valgrind in (RUSTC pointing at a wrapper script, or RUSTC_WRAPPER).

What I verified, and how

I checked the cargo side rather than assuming it, since that is the part that is easy to get wrong:

  • cargo honours RUSTC: with RUSTC set to a wrapper script that logs its arguments and then execs the real compiler, a cargo build routed all four of its compiler invocations through the wrapper, and the build succeeded.
  • RUSTC is a program path, not a command line: with RUSTC="<tool> <path-to-rustc>", cargo failed with could not execute process ... never executed, i.e. it looked for a program with that whole string as its name. So the form suggested in the issue, env RUSTC="valgrind $(rustup which rustc)", does not work as written, which is why the page uses a wrapper script. RUSTC_WRAPPER behaves the same way: it too rejects a value with arguments.
  • RUSTC_WRAPPER receives the path to rustc as its first argument: logging the wrapper's arguments showed ARG1=[...\bin\rustc.exe] ARG2=[-vV].
  • rustc on PATH is not the same file as rustup which rustc (...\.cargo\bin\rustc.exe versus ...\.rustup\toolchains\...\bin\rustc.exe), which is the second trap.

The Valgrind-side facts are from its manuals, which I read rather than recalled: callgrind.out.<pid> and callgrind_annotate, cachegrind.out.<pid> and cg_annotate, and the Callgrind manual's recommendation of KCachegrind. All five links added return HTTP 200.

One thing I could not verify: I am on Windows, where Valgrind does not run, so I could not produce an actual profile. The wrapper and RUSTC_WRAPPER mechanics above are observed, but the claim that the resulting file is a useful Callgrind profile rests on Valgrind's documentation. If a reviewer has a Linux machine, that is the step worth double-checking.

Checks

  • RUSTC_BOOTSTRAP=1 cargo run --release --manifest-path ci/sembr/Cargo.toml src reports src/profiling/with-valgrind.md as compliant, as it does for the two edited files.
  • No internal .html links; the only one in the touched files is the pre-existing external cargo --timings URL.
  • The new page is reachable from SUMMARY.md and linked from the profiling chapter's list.

The profiling chapter lists perf, Tracy and WPA, but not Valgrind, whose
Callgrind and Cachegrind tools measure something the sampling profilers
cannot: exact instruction counts, and simulated cache and branch
behaviour.

Add a page alongside the perf one. The interesting part is not running
Valgrind, it is getting it to profile the compiler: cargo runs rustc as a
subprocess, so `valgrind cargo build` profiles cargo, and the rustc in
PATH is usually the rustup shim rather than the compiler itself. Both
traps are covered, together with the fact that RUSTC names a program
rather than a command line.
@isHeSatoshi

This comment was marked as low quality.

@rustbot

rustbot commented Oct 19, 2026

Copy link
Copy Markdown
Collaborator

Thanks for the PR. If you have write access, feel free to merge this PR if it does not need reviews. You can request a review using r? rustc-dev-guide or r? <username>.

@rustbot rustbot added the S-waiting-on-review Status: this PR is waiting for a reviewer to verify its content label Oct 19, 2026
@BoxyUwU BoxyUwU closed this Oct 19, 2026
@rustbot rustbot removed the S-waiting-on-review Status: this PR is waiting for a reviewer to verify its content label Oct 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add information on running the compiler with cachegrind and valgrind

3 participants