Skip to content
Documentation

Docs / Adapter commands / Cargo

Cargo adapter

Restore Cargo state, reuse compiler results through sccache, run the build, and publish successful work with one command.

Command
boringcache cargo
Protocol
Cargo target-state reuse plus sccache-backed compiler cache
Action
mode: cargo

How the adapter works

Cargo home avoids dependency setup

Registry archives, registry metadata, and bare Git databases can restore without treating expanded sources as portable build output.

Target lets Cargo skip complete work

A target snapshot carries fingerprints, build-script output, and artifacts when its transfer cost is justified.

sccache reuses compiler results

When Cargo still invokes rustc, sccache can reuse matching compiler results without sharing one locked target directory across worktrees.

Set up Cargo

Choose the cache layers for the job. Keep the compiler-cache tag and these profiles in .boringcache.toml, then use boringcache cargo --profile cargo-deps --skip-save check --locked for repeated checks. It restores Cargo home and uses sccache while keeping each worktree's target local. Use the cargo-target profile only for a deliberate checkpoint. Fresh runners can use boringcache cargo build --release --locked when moving target state is faster than rebuilding it.

[adapters.sccache]
tag = "rust-main"

[profiles.cargo-deps]
entries = [
  "cargo-registry-cache",
  "cargo-registry-index",
  "cargo-git-db"
]

[profiles.cargo-target]
entries = ["cargo-target"]

Before the first run

  • Install Rust and Cargo before running the adapter.
  • Install sccache 0.16.0 or newer for compiler caching. Set compiler-cache = "none" under [adapters.cargo] to use Cargo archives without sccache.
  • Run boringcache onboard once, then commit the cargo-deps and cargo-target profiles. New CLI releases add both during onboarding.

Cargo builds and target snapshots

Choose a build lifecycle

For repeated local or worktree checks, run boringcache cargo --profile cargo-deps --skip-save check --locked; target stays local while sccache remains writable when the credential permits it.

When a trusted clean checkout should publish its existing target deliberately, run boringcache cargo --profile cargo-target --skip-restore check --locked --all-targets.

Use boringcache cargo build, boringcache cargo nextest run, or the complete [adapters.cargo] command when target transport is worth its restore and publication cost.

Source freshness and target identity

A Rust-target snapshot can warm a new worktree while changed source files stay newer than restored files.

Source, package version, manifest, and lockfile changes reuse the same target tag; Cargo rebuilds affected crates.

CLI 1.40.1 rebuilds standard-library crates once after first recording their sources for -Z build-std. The next CLI captures those sources before compilation, so the first warm build can reuse them when the source root, contents and successful-build evidence match. Changed or unverified sources, including symlinks, force a rebuild.

The next CLI includes initialized submodule sources and restores a directory timestamp only when all its contents are tracked and unchanged. Ignored, generated or symlinked directory inputs keep Cargo's freshness checks active.

The next CLI caches Cargo's separate build.build-dir when configured. Cargo recreates final outputs in the target directory from the restored intermediate files.

The target uses its configured tag with the existing platform and Git suffixes. Compiler versions do not add a suffix; Cargo decides which restored outputs need rebuilding.

Target snapshots carry package versions and locked dependency versions in .boringcache/cargo-build-v1.json for inspection. This metadata does not control restore, rebuilds, or cleanup.

Cargo home path

Cargo records each registry and Git dependency in target fingerprints by its absolute path under the Cargo home. A target restored where the Cargo home has a different path rebuilds every dependency. Moving the checkout does not cause this.

boringcache cargo runs Cargo with the machine's own Cargo home and never changes it. CLI releases after 1.46.0 record that path with each saved target and warn, naming both paths, when a restored target was built under a different Cargo home.

To share targets, give every machine the same absolute Cargo home and set CARGO_HOME to it before installing Rust. The official Rust container images use /usr/local/cargo, so the same path on other machines also matches targets built in those images. Where /usr/local belongs to root, create the directory once with sudo install -d -o "$USER" /usr/local/cargo, then add $CARGO_HOME/bin to PATH. In CI, set CARGO_HOME in the job environment before the step that installs Rust, and keep it set for later steps. The first build after the change misses the compiler cache because sccache keys include CARGO_HOME.

Incremental compilation and exclusions

CARGO_INCREMENTAL defaults to 0, which excludes Cargo incremental directories from saves. Set CARGO_INCREMENTAL=1 to enable incremental compilation and include those directories; use compiler-cache = "none" because sccache requires incremental compilation to be disabled. The rustc query cache and obsolete BoringCache artifact receipt stay excluded.

A dirty checkout never publishes a target snapshot. Set compiler-cache = "none" for target-state reuse without sccache.

To omit files from target saves, add exclude = ["*.tmp", "scratch/"] under [entries.cargo-target]. For one invocation, use boringcache cargo --exclude-pattern '*.tmp' build. These use the existing archive pattern rules and do not read .gitignore or change compiler caching.

Cargo target pruning

When pruning runs

Prerelease CLI builds prune Cargo targets with a default budget of 40 GiB after successful commands that report Cargo JSON build messages when neither stdout nor stderr is a terminal, including read-only runs and --skip-save.

Terminal commands inherit their streams and skip observation, preserving progress, colors and interactive programs. Unobserved commands invalidate existing usage evidence. Automatic pruning is intended for CI and other non-interactive runs. A terminal-only workflow does not produce usable evidence for standalone pruning; local scripts with both output streams redirected can record usage.

Budget and offline cleanup

Override target-budget under [adapters.cargo] or --target-budget on the command line.

Active outputs, unknown files, and groups without unchanged usage evidence are preserved even when they exceed the budget. Run boringcache prune cargo --target-dir target --dry-run to preview cleanup from recorded usage, or omit --dry-run to apply it; --json reports exact byte counts. Pruning works offline without a service connection.

Flags override project settings, which override the CLI default; a budget of 0 disables pruning. Command-line overrides apply only to that invocation. GB and GiB both use binary bytes, matching other cache size settings. TB and TiB are not accepted; use GiB for larger budgets.

Budget and offline cleanup
boringcache prune cargo --target-dir target --dry-run
boringcache prune cargo --target-dir target --dry-run --json

Output observation

When a command has no --message-format, the CLI adds --message-format=json-render-diagnostics directly after the Cargo subcommand, reads the JSON from the child stdout pipe and does not print it. Cargo progress and rendered diagnostics stay on stderr, application and test output is unchanged, and Cargo is never run twice. The flag is added when cargo <command> --help lists json-render-diagnostics, and cargo clippy uses the cargo check options it forwards to; there is no command-name allowlist.

Aliases and plugins

Aliases qualify when every argument in their expansion is an option. Aliases with -- or positional arguments, such as xtask = "run --package xtask --", run unchanged and are not observed. External plugins such as cargo fuzz receive their arguments unchanged. On Unix, the CLI starts a plugin with a temporary cargo shim first on PATH, so each target-using Cargo command that the plugin starts through PATH gets the added format, and pruning combines the usage of every recorded command, such as the cargo build and cargo run that cargo fuzz run starts.

The target is preserved when one of those commands fails, is still running when the plugin exits, or cannot be observed, and when the plugin starts no Cargo command through PATH. A plugin command that starts no Cargo command, such as boringcache cargo fuzz list, leaves usage incomplete, so existing outputs stay protected until a later command uses them; run such commands without boringcache.

A Cargo command that the plugin leaves in the background also preserves the target if it starts before pruning takes Cargo's build lock; a later command waits for that lock and rebuilds any removed output it needs. A command that a plugin starts through $CARGO or an absolute path is not seen; outputs used only by such a command can be removed and are rebuilt when they are next used.

Explicit JSON output

A command that passes a JSON --message-format itself keeps its stdout byte for byte, including plugins that forward the flag to Cargo; other formats such as short skip observation. To save the stream, pass the format and redirect the outer command: boringcache cargo build --message-format=json >cargo-build.jsonl 2>cargo-build.log. Cargo emits JSON on stdout; it has no separate JSON output-file option. Both streams must be non-terminal. For run and test, stdout also includes application or test output after the build messages.

Explicit JSON output
boringcache cargo build --message-format=json >cargo-build.jsonl 2>cargo-build.log

Protected outputs and concurrency

Use the same explicit --target-scope ID on consecutive wrapped commands to protect their combined outputs. CI job IDs do not affect retention. Nested or overlapping commands run without pruning. Waiting for the pruning record lock is limited to 30 seconds; if a large or slow pruning pass holds it longer, the waiting command fails before launch. Groups containing symlinks, and incremental/ when enabled, remain protected; other recognized groups can still be pruned. If descendants keep output open after exit, forwarding stops after five seconds, the command result is preserved and pruning is skipped.

Complete build evidence

Unobserved commands, failed commands, and incomplete observations do not authorize deletion. A JSON message format alone is insufficient: the command must emit artifact or build-script outputs and a successful build-finished message, then exit successfully. Each invocation must emit one complete build stream. Additional build messages after build-finished invalidate usage and preserve all outputs. Bare Cargo commands between --phase restore and --phase save are not observed, so those phases do not automatically prune. The next CLI reports this whenever the configured pruning budget is positive, including the default budget.

Target directories

With a separate build.build-dir, that intermediate directory is the cache and pruning boundary; final outputs remain in Cargo's target directory. Pruning recognizes both Cargo target layouts: the classic profile layout with .fingerprint and deps, and the per-unit build/<package>/<hash> layout that nightly Cargo uses by default. Previously unrecorded outputs remain protected until a wrapped command observes them.

Docker target mounts

With prerelease workers, managed Docker target mounts observe Cargo when the build runs through boringcache docker --mount-cache: the worker puts a cargo shim first on the RUN command's PATH, so a plain RUN cargo build --release gets the added message format and its JSON goes to a worker-local file instead of the build log. Commands that are not observed, including aliases and plugins that can use the target, keep the target for that step; Cargo invoked by absolute path is not seen.

Several target-using Cargo commands with the added format in one step combine their usage; a command that passes its own JSON --message-format keeps the target unless it is the step's only target-using Cargo command. A command that passes its own JSON --message-format can copy stdout to "$BORINGCACHE_CARGO_MESSAGE_FILE" using tee or redirection; for a pipeline, use Bash with pipefail so a Cargo failure is preserved. The worker creates a fresh file before each command, inherits the command streams, reads the file after successful exit, prunes before cache publication, and removes the temporary file.

It uses the same target-budget configuration and protects uncertain outputs. With a zero budget, the worker still provides the temporary file so existing pipelines work, but it skips observation and pruning. Each file must contain one complete Cargo build stream; empty, incomplete, failed or concatenated streams skip pruning. Corrupt or unreadable usage records produce a warning and skip worker pruning; the message file remains available and the command keeps its exit status. Record-lock timeouts still fail before command execution. Ordinary Docker cache mounts do not provide this variable.

Concurrent shared-cache merges can restore remotely published files; the local budget does not change remote retention.

Cargo unit timings

What is recorded

With the default sccache compiler cache, the next CLI adds --timings after the Cargo subcommand for build, check, test, bench, run, rustc, doc, rustdoc and fix. Cargo writes its timing report under the target directory. After the command, the CLI reads the report, removes the report it added before the target can be saved, and prints one summary line. Cargo still prints the report path before the CLI removes it. The flag does not change rustc arguments, Cargo fingerprints or compiler-cache keys.

The run page and the run API show the slowest units Cargo compiled or ran, with crate, version, target and features; the number of fresh units; the chain of units in which each was the last dependency to finish before the next became ready; and the time ready units waited for a job slot, with Cargo's job and CPU counts. A failed build keeps the units Cargo reached.

Cargo lists only the units it compiled or ran, and fresh units only as a count. It does not report whether sccache served a compilation, and it does not time tests or programs. The chain of last dependencies is not an estimate of time saved.

Commands without unit timings

A command that passes --timings keeps its report, and the CLI reads it. Cargo older than 1.60 has no --timings, so its commands run unchanged and record no units. A command that passes a JSON --message-format keeps its stdout unchanged and records no units, because Cargo adds a build-started message to JSON output when timings are on. Plugins such as clippy and nextest, cargo install, commands with compiler-cache = "none", and runs without cache credentials also record no units.

Reuse target snapshots between local worktrees

CLI 1.32.0 adds optional local target snapshots. Enable them in .boringcache.toml to restore an empty target in another worktree of the same Git repository. Each worktree gets independent files or filesystem clones and keeps its own writable target.

.boringcache.toml
[adapters.cargo.local-target-cache]
enabled = true
max-size = "20GiB"

The default is off. Include cargo-target in the selected profile to capture a snapshot. With CLI 1.33.0 or later, cargo-deps can restore an existing local snapshot into an empty target without transferring a remote target archive or capturing a new snapshot. Worktrees must use the same target tag and exclusions. Existing populated targets are kept.

Local snapshots need no remote credential. A successful build in a clean checkout can capture a snapshot; dirty checkouts do not publish one. The default disk budget is 20 GiB of logical file bytes, with least-recently-restored snapshots removed when space is needed.

Run boringcache cargo --profile cargo-target build --locked in the original checkout, then in an empty worktree. The CLI reports capture or restore; Cargo decides which outputs are still fresh. An oversized or busy target is skipped with a reason.

Use the same adapter in GitHub Actions

With CLI and Action 1.31.0 or later, omit [adapters.cargo].command to restore in this step and publish after the job. Run ordinary Cargo commands in later steps. A committed command runs the complete lifecycle in the Action step. Use only one Cargo Action step per job.

.github/workflows/ci.yml
- uses: boringcache/one@1781572d7b3ec5aef652f8ba479b981439b2776b # v1.48.2
  with:
    trust-policy: auto
    mode: cargo

- run: cargo test --locked

Approve the repository through Connect CI and grant the job contents: read and id-token: write. The Action uses that Machine connection. Pull requests restore by default; trusted jobs may publish. See the authentication example in the GitHub Actions reference for scoped credentials when OIDC is unavailable.

GitHub Actions reference

Cache several Cargo commands in one job

CLI 1.31.0 or later can restore before a job's Cargo commands and save afterward. A phase runs no Cargo command and ignores [adapters.cargo].command. It cannot be combined with a command, --skip-restore, or --skip-save.

Direct CLI phases
boringcache cargo --phase restore
cargo check --locked
cargo test --locked
boringcache cargo --phase save

In GitHub Actions, omit [adapters.cargo].command and use one mode: cargo step before ordinary Cargo steps. BoringCache One restores in its main step, exports the cache environment, and publishes in its post step. A committed command keeps the complete lifecycle inside the Action step.

Choose save: always to publish the state a job reached after a failed step, or save: never to disable publication. The default is save: on-success. Trust policy, credentials, and the dirty-checkout rule still apply. A failed command embedded in the repo plan does not publish through the post step.

Direct CLI phases transfer archives only; they do not start the compiler-cache proxy. Use the wrapped command or the Action when you also need sccache setup.

Benchmarks

Deno, Zed, Zed on Namespace runners, and Zed release bundle build the same upstream commits with BoringCache, Depot Cache, GHA Cache, kache, GHA Cache + target, mr-boxington and Depot runner cache on the same runner classes.

Zed

Rust

Benchmark →

Code editor written in Rust.

Average restore, build and save · lower is better

GitHub runner

4 vCPU · 16 GB · Ubuntu 24.04 x86-64

Base · sccache compiler cache

BoringCache
30 min 45 s 30 builds
Depot Cache
30 min 38 s 30 builds
GHA Cache
32 min 29 s 30 builds
kache
31 min 57 s 30 builds

Plus · sccache, Cargo registry and target directory

BoringCache +
30 min 27 s 30 builds
GHA Cache + target
39 min 0 s 30 builds
mr-boxington
48 min 53 s 30 builds
Same CPU model

Builds of one commit can land on different CPU models. These ratios use only the build pairs where both caches ran on the same model; above 1.00× means BoringCache's total time over those pairs was lower.

Depot Cache vs BoringCache
1.03× · 8 of 30
GHA Cache vs BoringCache
1.03× · 15 of 30
kache vs BoringCache
1.24× · 5 of 30
GHA Cache + target vs BoringCache +
1.21× · 6 of 30
mr-boxington vs BoringCache +
1.78× · 9 of 30
6 CPU models recorded
BoringCache · sccache compiler cache
AMD EPYC 7763 (17 builds) · AMD EPYC 9V74 (6 builds) · AMD EPYC 9V45 (5 builds) · Intel Xeon 6973P-C (1 build) · Intel Xeon Platinum 8573C (1 build)
BoringCache + · sccache, Cargo registry and target directory
AMD EPYC 7763 (14 builds) · AMD EPYC 9V74 (6 builds) · Intel Xeon Platinum 8573C (6 builds) · AMD EPYC 9V45 (2 builds) · Intel Xeon 6973P-C (1 build) · Intel Xeon Platinum 8370C (1 build)
Depot Cache · sccache WebDAV backend
AMD EPYC 7763 (11 builds) · AMD EPYC 9V45 (10 builds) · AMD EPYC 9V74 (4 builds) · Intel Xeon Platinum 8573C (3 builds) · Intel Xeon 6973P-C (2 builds)
GHA Cache · sccache GitHub Actions backend
AMD EPYC 7763 (19 builds) · AMD EPYC 9V45 (5 builds) · AMD EPYC 9V74 (4 builds) · Intel Xeon 6973P-C (1 build) · Intel Xeon Platinum 8573C (1 build)
kache
AMD EPYC 7763 (11 builds) · AMD EPYC 9V45 (10 builds) · AMD EPYC 9V74 (5 builds) · Intel Xeon Platinum 8573C (2 builds) · Intel Xeon Platinum 8370C (2 builds)
GHA Cache + target · sccache plus actions/cache for registry and target
AMD EPYC 7763 (11 builds) · AMD EPYC 9V74 (5 builds) · Intel Xeon Platinum 8370C (4 builds) · AMD EPYC 9V45 (4 builds) · Intel Xeon Platinum 8573C (4 builds) · Intel Xeon 6973P-C (2 builds)
mr-boxington
AMD EPYC 7763 (13 builds) · AMD EPYC 9V45 (6 builds) · Intel Xeon Platinum 8573C (5 builds) · AMD EPYC 9V74 (4 builds) · Intel Xeon Platinum 8370C (2 builds)
Cold and warm builds

Each table is one workflow run with one build per cache. A row marked Different CPU ran on another CPU model than BoringCache at the same level, so part of its time difference can come from the hardware.

One cold and warm build per cache
Cache Cold Warm CPU
Base · sccache compiler cache
BoringCache sccache compiler cache 34 min 31 s 15 min 45 s AMD EPYC 9V45
Depot Cache sccache WebDAV backend 51 min 8 s 21 min 0 s AMD EPYC 7763 Different CPU
GHA Cache sccache GitHub Actions backend 48 min 54 s 21 min 51 s Cold: AMD EPYC 7763 · Warm: AMD EPYC 9V74 Different CPU
kache 42 min 21 s 5 min 0 s Cold: Intel Xeon 6973P-C · Warm: AMD EPYC 7763 Different CPU
Plus · sccache, Cargo registry and target directory
BoringCache + sccache, Cargo registry and target directory 51 min 8 s 12 min 54 s Cold: AMD EPYC 7763 · Warm: AMD EPYC 9V45
GHA Cache + target sccache plus actions/cache for registry and target 41 min 31 s 36 min 30 s Cold: AMD EPYC 9V74 · Warm: AMD EPYC 7763 Different CPU
mr-boxington 34 min 59 s 40 min 3 s Cold: AMD EPYC 9V45 · Warm: AMD EPYC 9V74 Different CPU

Cache hits

BoringCache · GitHub runner · 4 vCPU

95.0% of 60,173 lookups over 30 builds

Served from the runner
Under 1 ms per read
Measured by sccache
3.4 ms per hit
Read from cache
46.1 GB

Tool reference

Check the tool's own reference when you need cache-key rules, build settings, or version-specific behavior.

All adapter commands

Compare every supported command, protocol, and Action mode in one place.

Adapter command index →

Need help or found something unclear? Open an issue or browse the CLI repo.