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.

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.
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:
-Zthreads | cold hir-ty |
|---|---|
| 1 | 3.53s |
| 2 | 2.38s |
| 4 | 1.67s |
| 8 | 1.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:
| project | baseline cold | adaptive | speedup |
|---|---|---|---|
| tokio | 11.69s | 3.13s | 3.73x |
| ripgrep | 5.35s | 2.89s | 1.85x |
| rust-analyzer | 26.28s | 16.91s | 1.55x |
| clap | 1.54s | 1.14s | 1.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.
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.
| project | units | baseline cold | cached cold | cargo’s no-op floor | speedup |
|---|---|---|---|---|---|
| rust-analyzer | 239 | 23.77s | 0.47s | 0.10s | 50.6x |
| ripgrep | 46 | 5.37s | 0.18s | 0.03s | 29.8x |
| tokio | 40 | 4.66s | 0.17s | 0.04s | 27.4x |
| solo, zero dependencies | 1 | 3.28s | 0.09s | 0.01s | 36.4x |
| clap | 23 | 1.54s | 0.15s | 0.04s | 10.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.
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
| file | lines | what it does |
|---|---|---|
cargo/src/compiler/shared_cache.rs | 596 | machine-wide artifact cache, new |
cargo/src/compiler/fingerprint/interface_hash.rs | 808 | cutoff planning, metadata pinning, new |
cargo/src/compiler/job_queue/unit_costs.rs | 276 | schedule by measured unit cost, new |
cargo/src/compiler/frontend_threads.rs | 133 | graph-shaped thread allocation, new |
cargo edits across 9 files | 431 added, 38 removed | wiring, flags, docs, snapshot |
rustc/compiler/rustc_metadata/src/interface_hash.rs | 302 | interface and surface hashes, new |
rustc edits across 9 files | 237 added, 5 removed | flags, 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.
| project | cargo check | cargo turbo, first run | cargo turbo, target wiped |
|---|---|---|---|
| rust-analyzer | 23.07s | 16.38s | 0.77s (30.0x) |
| ripgrep | 5.33s | 3.03s | 0.21s (25.4x) |
| tokio | 4.61s | 3.03s | 0.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-analyzer | stable 1.97.1 | nightly 1.100.0 |
|---|---|---|
| first build | 23.80s | 16.38s |
| target directory wiped, sources untouched | 0.57s | 0.77s |
| every source timestamp changed | 6.73s, 51 of 309 units rebuilt | 2.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.



