Software EngineeringRustPerformance

Cutting a Cold cargo check From 23.77s to 0.47s on an M4

A cold cargo check of rust-analyzer goes from 23.77s to 0.47s. Three changes across cargo and rustc, what each one bought, and how two of them ship as a separate tool that patches nothing.

A dependency graph whose lower half is wide and fully parallel, narrowing to a single vertical chain at the top, with the chain highlighted as the critical path.
Lead image A dependency graph whose lower half is wide and fully parallel, narrowing to a single vertical chain at the top, with the chain highlighted as the critical path.
On this page

Audio edition

0:00 / 17:12

Ready

Rust’s compiler has a reputation, and I wanted to know how much of it survives measurement. Everything below ran on an Apple M4 with 10 cores and 16 GB of memory, on macOS 15.7.2, against rustc 1.100.0-nightly (67854e511 2026-08-15). The test projects are rust-analyzer at 239 units, tokio , ripgrep and clap . I also generated a single crate of 36,000 lines with no dependencies at all, which I call solo . It exists to separate the cost of your own code from the cost of everybody else’s.

A cold cargo check of rust-analyzer, from an empty target directory, went from 23.77 seconds to 0.47 seconds.

Both patches, every script that produced a number here, and the full measurement log live in drmhse/rust-performance . The same work sits on the rust-performance branch of drmhse/cargo and drmhse/rust against the upstream commits they apply to.

Core utilisation during a cold check

A cold check of rust-analyzer takes 25.94 seconds of wall clock and burns 53.56 seconds of user time plus 7.08 seconds of system time. On a 10 core machine that averages 2.34 cores. I wrapped rustc in a script that logs a start and end timestamp per invocation, and the shape came out of that log.

Bar chart of units compiling at once over a 42 second cold build. For the first 17.5 seconds the bars sit between 12 and 23. After a marked divider the bars drop to one or two and stay there for the remaining 25 seconds.
Measured with a rustc wrapper that timestamps every invocation. The red section is where the machine has nothing to do.

For 17.5 seconds an average of 15.9 units are in flight, peaking at 23, while registry dependencies compile. For the remaining 25 seconds the average is 1.46, because the workspace crates form a chain and each one waits for the metadata of the one below it.

The same log answers a second question. Of 288 units, 250 are third-party dependencies, and they account for 130.7 seconds of the 170.8 seconds of CPU, which is 77%.

Inside a single compilation, -Ztime-passes on a warm re-check of hir-ty gives 0.819 seconds total, split as macro expansion 0.297, name resolution 0.087, dep-graph serialisation 0.087, and type checking 0.048. Type checking, the thing everyone blames, is 6% of a check.

So the build I started from leaves most of the machine idle. It spends three quarters of its effort on code nobody in the project wrote, and most of each compilation on parsing and bookkeeping.

Threads inside one rustc invocation

rustc can use several threads inside one compilation, through -Zthreads. I had measured that flag earlier on an incremental re-check and recorded it as useless, at 1.44 seconds against 1.45. That measurement was taken in the wrong regime, because an incremental re-check has almost nothing to redo and threads have nothing to divide.

On a cold compile of hir-ty the same flag behaves completely differently:

-Zthreadscold hir-ty
13.53s
22.38s
41.67s
81.56s

Handing every unit eight threads makes things worse, because the fan-out phase already fills the machine. Blanket RUSTFLAGS=-Zthreads=8 took rust-analyzer’s cold check from 26.28 seconds to 39.08, which is slower than doing nothing.

The allocation has to follow the shape of the graph, so src/compiler/frontend_threads.rs computes each unit’s longest-path depth, counts how many units share that depth, and gives each unit clamp(jobs / width, 1, 8) threads. Units in the wide fan-out get one thread each; the single unit in the tail gets the whole machine. Longest path rather than shortest, because a unit is ready only once its slowest dependency chain finishes.

That is 133 lines, exposed as -Zadaptive-threads, and it bought this:

projectbaseline coldadaptivespeedup
tokio11.69s3.13s3.73x
ripgrep5.35s2.89s1.85x
rust-analyzer26.28s16.91s1.55x
clap1.54s1.14s1.35x

CPU cost rises 13%, against 24% for the blanket version that ran slower.

A machine-wide cache for identical crate builds

The 77% figure points somewhere obvious. A given version of syn, built with the same features, profile and compiler, produces the same bytes every time. Cargo rebuilds it once per target directory anyway, forever.

src/compiler/shared_cache.rs , 596 lines behind -Zshared-cache, records each built unit under a key covering everything that determined its output, and restores it on any later build that asks for the same thing. For registry packages the key is cargo’s own fingerprint hash, which already covers package identity, features, profile, every rustc flag, the compiler version, and transitively the fingerprints of dependencies.

A local package needs more than that, and the four requirements below are what make the key trustworthy. Each one is there because the cache is only worth having if it is never wrong.

The key covers the source, not the timestamps. Cargo decides a local unit’s freshness by comparing file mtimes, and mtimes are not part of the fingerprint hash. Two different versions of your own code can therefore share one, so the key folds in a digest of every file under the package root. The digest deliberately covers more than the crate compiles: hashing an irrelevant file costs a cache miss, while missing a relevant one would hand back the wrong build.

The key is transitive. A unit’s fingerprint records which dependencies it had rather than what they contained. Each dependency’s key is therefore folded into the key above it, memoised in BuildRunner::cache_keys because the graph walk is otherwise exponential. Editing a function in a leaf crate therefore changes the key of every crate that can see it.

Whatever a build script declared it reads is verified on restore. A script’s inputs are only known after it has run, so they cannot go into the key on a cold build. The entry records each rerun-if-changed path with a digest, and a restore is refused if any of them has changed. Those paths routinely sit outside the package root. A script that stages a sibling directory into OUT_DIR, which the crate then embeds with include_dir!, has an input nothing else in the key can see.

The cache is immutable. Storing copies rather than hard-links, because a link would make the cached entry and the build directory’s file one inode. Anything rewriting that file in place would then rewrite the cache with it. Restoring links freely in the other direction, since rustc replaces its outputs by rename.

Restoration runs deepest-first, and this is the single change that decided whether any of it was worth having. Cargo prepares a unit before it recurses into that unit’s dependencies, so a unit’s fingerprint is computed while its dependencies’ outputs are still absent, and it memoises them as stale. Restoring a dependency after that point is invisible: the dependent has already recorded that it was missing.

Two columns showing the same three crates, hir_ty above vfs above stdx. On the left the numbers one, two and three run top to bottom, and hir_ty is marked because its fingerprint is decided while the crates below it are still absent. On the right the numbers run bottom to top, so every dependency is on disk before the unit above it is judged.
The same restores, in two orders. Only one of them is visible to cargo.

restore_from_shared_cache walks dependencies first, restoring each and recomputing its fingerprint before any freshness decision is made, and calls prepare_init per unit because cargo creates fingerprint directories later than this walk reaches them. Ordering alone took rust-analyzer from 3.0 seconds to 0.47.

Build script runs are cached whole, including their OUT_DIR, because they sit at the bottom of the graph and re-running one marks every crate above it as having had a dependency rebuilt. Two files inside the run directory name the directory itself and are rewritten on restore. root-output always holds its own absolute path, and the directives file is where a C library reports where it put its archive. Anything else under the directory that embeds the path is refused, because a static archive cannot be repaired by text substitution. Handling the directives case is what took ripgrep from 2.9x to 29.8x, since its pcre2-sys dependency compiles a C library and emits rustc-link-search pointing at the result. A full cargo build still links it.

projectunitsbaseline coldcached coldcargo’s no-op floorspeedup
rust-analyzer23923.77s0.47s0.10s50.6x
ripgrep465.37s0.18s0.03s29.8x
tokio404.66s0.17s0.04s27.4x
solo, zero dependencies13.28s0.09s0.01s36.4x
clap231.54s0.15s0.04s10.3x

The whole cache for all five projects is 346 MB. The no-op column is what cargo costs when it decides a fully built directory needs nothing. That is the floor any approach of this kind can reach, and rust-analyzer’s 0.47 seconds is within a factor of five of it.

The solo row matters more than its size suggests. A project with zero dependencies and a project with 239 units land at 36.4x and 50.6x, which says the distinction between them disappears once both are cached.

Re-checks triggered by unchanged interfaces

Cold builds are one problem, and editing a file is another. When I change one private function in stdx, cargo re-checks 31 units, because its signal is “the dependency was rebuilt” and rustc’s crate hash changes whenever any line does.

-Zinterface-hash adds a second hash, computed in compiler/rustc_metadata/src/interface_hash.rs , over only the cross-crate type-level surface: def paths, kinds, visibilities, types, signatures, generics, predicates, ADT shape, and impls. Function bodies are excluded, spans are excluded through while_hashing_spans(false), and const-evaluatable bodies are included because a dependent can observe them through an array length. Cargo compares those hashes inside the running job, since a dependency’s new hash does not exist until it rebuilds. Editing that private function now runs 1 unit instead of 31, in 0.20 seconds instead of 6.66.

Skipping a crate carries one requirement that is easy to miss. rustc stamps each dependency’s crate hash into the metadata it emits, and that hash covers the whole crate, so a single edited line moves it. A crate that was skipped therefore holds metadata naming a hash that is no longer on disk, and nothing detects that until a later edit forces one of those crates to compile.

Two panels. In the first, editing stdx rebuilds it to hash h2 while hir_def is skipped and still records h1, and nothing fails. In the second, editing hir_ty forces it to compile, and it loads a stdx that is h2 alongside a hir_def that wants h1, which produces error E0463.
Why a rebuilt crate has to keep its previous metadata: the mismatch surfaces an edit later, in a crate nobody touched.

So a unit’s metadata is hard-linked aside before rustc runs and renamed back when the unit’s interface hash is unchanged and its dependencies’ hashes are unchanged. Both conditions are required: restoring one crate’s previous metadata while its dependency carries a new crate hash moves the same mismatch one level up. The file is selected by extension rather than by FileFlavor::Rmeta, because a check unit’s metadata is its primary output and carries the Normal flavor.

The changes and their size

filelineswhat it does
cargo/src/compiler/shared_cache.rs596machine-wide artifact cache, new
cargo/src/compiler/fingerprint/interface_hash.rs808cutoff planning, metadata pinning, new
cargo/src/compiler/job_queue/unit_costs.rs276schedule by measured unit cost, new
cargo/src/compiler/frontend_threads.rs133graph-shaped thread allocation, new
cargo edits across 9 files431 added, 38 removedwiring, flags, docs, snapshot
rustc/compiler/rustc_metadata/src/interface_hash.rs302interface and surface hashes, new
rustc edits across 9 files237 added, 5 removedflags, read sets, early metadata, counters

That is 2,577 lines added to cargo and 539 to rustc, behind four unstable flags (-Zinterface-hash, -Zadaptive-threads, -Zshared-cache, -Zearly-metadata). Both patches are in patches/ , verified to apply cleanly to the upstream commits named there, and every table above is reproducible through harness/ . unit_costs.rs carries no speedup of its own here: it replaces a hardcoded scheduling constant with measured per-unit costs under -Zbuild-analysis, and its effect is not separated from the three changes above it.

Validation is 4,357 cargo testsuite tests passing with one pre-existing cross-compile environment failure, 6 unit tests on the cache, 4 on thread allocation, 50 on the fingerprint module, and two differential harnesses. The cache harness wipes the target directory at every step of a 10 edit sequence, and compares exit codes against an uncached cargo, including deliberate type errors. The cutoff harness runs 12 sequential edits across four crates. Both are in harness/ , and both agree at every step. The sequence is the point: one edit followed by one check cannot detect an artifact set that disagrees with itself, because nothing has to load the artifacts that disagree.

Two of the three changes as a separate tool

Two of the three changes turn out not to need a patch at all, and one of them is better without one. Stock cargo already exposes enough to build them as a separate tool. RUSTC_WRAPPER is invoked as wrapper <real-rustc> <args> for every compilation. cargo build --unit-graph -Z unstable-options prints all 309 units with their dependencies. -Zchecksum-freshness compares file contents instead of timestamps.

Thread allocation is better as a wrapper. A wrapper registers each invocation in a directory and counts its siblings. The share then reflects how wide the build is at that moment, rather than how wide a depth-and-width analysis predicted. In a run measuring all three together against a 27.51s baseline, the wrapper reached 19.37s and the in-cargo version 21.21s. The graph says how wide a build could be; the count says how wide it is.

The cache can be a target-directory snapshot. Cargo decides freshness before it would consult any external cache, so nothing outside cargo can mark one unit fresh. It can hand cargo a directory that already holds the answer and let cargo’s own freshness pass conclude there is nothing to do.

cargo-turbo is those two mechanisms in 687 lines with no dependencies. The snapshot is keyed on the resolved dependency set, the compiler and cargo versions, the build flags, and the environment variables cargo folds into its own fingerprints.

projectcargo checkcargo turbo, first runcargo turbo, target wiped
rust-analyzer23.07s16.38s0.77s (30.0x)
ripgrep5.33s3.03s0.21s (25.4x)
tokio4.61s3.03s0.19s (24.3x)

Two mechanics decide whether this works. Copy-on-write clones make snapshots nearly free. cp -Rpc on APFS and --reflink=auto on Btrfs share blocks until one copy is written. A store reporting 2.6 GB consumed 2 MB of actual disk, measured as free-space delta rather than by asking du. And -Zchecksum-freshness has to be set for the recording build as well as the restore. Fingerprints written in timestamp mode are rejected wholesale by checksum mode, so restoring one and then checking with checksums rebuilds everything, at 24.69s. Without checksums at all, a fresh clone gives every source a newer timestamp than the outputs built from it, which rebuilds everything for the same reason.

Both unstable flags it uses are available only on nightly, so stable is worth measuring separately. A mtime-preserving clone needs no flag at all, so the snapshot still restores there. What stable gives up is the thread allocation, and independence from timestamps.

rust-analyzerstable 1.97.1nightly 1.100.0
first build23.80s16.38s
target directory wiped, sources untouched0.57s0.77s
every source timestamp changed6.73s, 51 of 309 units rebuilt2.11s, 4 units rebuilt

Stable rebuilds the crates whose sources look newer, and keeps the dependencies, because those sit in the registry with their timestamps untouched. That is most of the work either way. The four units that still rebuild on nightly are build scripts and their dependents, since cargo compares timestamps for the paths a build script declares even under checksum freshness.

The patches keep a factor of about 2.5, at 0.47s against 0.77s, for two things a wrapper cannot reach. They let cargo treat a unit as fresh without spawning rustc at all, and they cache build script executions, which RUSTC_WRAPPER never sees. On a project vendoring OpenSSL that second point was the difference between 2.57x and 19x. The interface hash is the one piece that genuinely requires rustc, since a crate’s cross-crate type surface exists only inside the compiler.

Limitations

The first build of code that has never been built anywhere still costs full price, and nothing here changes that. The gains come from CI, fresh clones, wiped target directories, branch switching, and projects that share dependencies.

The cache is machine-local on purpose. A build script can read a system library or an environment variable that cargo never fingerprints, so its result is only reliably reusable where those are the same. Sharing it across machines needs a way to prove that a script observed nothing outside its declared inputs, and I do not have one.

Every measurement in this post is recorded with the hardware and compiler that produced it in results/ .

The single-crate ceiling is the honest limit. solo compiles in 2.55 seconds of CPU, so perfect scaling across 10 cores would be 0.26 seconds. rustc’s parallel frontend currently reaches 1.16 seconds, by burning 1.9x the CPU. Closing that gap means making the frontend scale, which is a rustc-architecture problem well beyond a patch.

Continue reading

Complete index →