Conformance to the specification

P0 checklist

Not in this release (P1 and later in the specification)

Controlled GC execution, remote-cache administration and read-only cache mode, central service and organization policy, PR annotations, container analysis (FR-140), the plugin protocol (FR-180), nightly --unit-graph / -Zbuild-analysis / section-timing adapters, the metadata-embedding experiment, and network / disk-I/O telemetry. Nightly capabilities are detected and listed in toolchain.capabilities; nothing depends on them.

Deviations and decisions

1. CARGO is QuickRust’s cargo (COMP-030), by running Cargo under another name. Cargo hands everything it starts (external subcommands, build scripts, env!("CARGO"), test binaries) its own path, and takes an inherited CARGO instead only when its own executable is not named cargo (Cargo 1.86 and later), or, after that, the path in its argv[0] when that is named cargo. QuickRust therefore runs a hard link of the toolchain’s cargo, bin/.qrust-engine, with argv[0] and CARGO set to ~/.qrust/bin/cargo (Windows has no separate argv[0]: there Cargo’s help names the link, .qrust-engine.exe): a nested build through $CARGO (Clippy’s, nextest’s, cargo llvm-cov’s) is a QuickRust session linked to its parent (COMP-031), with QuickRust’s settings, like one through PATH. Either can be opted out with QRUST_NESTED=upstream (COMP-032). qrust upstream runs the toolchain’s cargo as itself, and a linked toolchain is never changed, so there nested builds through $CARGO reach that Cargo directly; their rustc invocations are still observed, because RUSTC_WRAPPER is inherited.

2. Run state lives in ~/.qrust, not in the repository. The specification’s configuration example writes reports to .qrust/runs/. Creating files in a repository on every cargo build is not something a drop-in replacement should do, so recording goes to QRUST_HOME and a repository report path is opt-in (measurement.report, QRUST_REPORT).

3. Analysis is lazy by default. To keep dispatch overhead inside NFR-PERF-001/003, the build path only records; reports are produced on demand or synchronously when a report or budget enforcement was requested. A run analysed after later runs keeps everything recorded at build time (units, timings, revision) and reports workspace metadata, dirtiness and the artifact footprint as unavailable rather than describing today’s tree.

4. Fresh units need Cargo’s JSON stream. On a stable toolchain, nothing else says which units Cargo considered fresh. QuickRust observes the stream only when the user already asked for it and stdout is not a terminal, so terminal behaviour is never altered; otherwise units_fresh is null with a reason.

5. Build-script run time is taken from files Cargo writes around the run (invoked.timestamp, then stderr / root-output). Cargo back-dates output to the invocation time, so it cannot be used.

6. QuickRust manages the toolchains (decision of 2026-10-12), not rustup (COMP-020). The specification resolves an upstream Cargo through PATH and rustup. QuickRust instead installs toolchains from the Rust dist server into ~/.qrust/toolchains and selects them in rustup’s documented order (+toolchain, RUSTUP_TOOLCHAIN, toolchain file, default; rustup’s per-directory overrides have no equivalent). Every command runs that toolchain’s own Cargo with QuickRust’s Cargo home (~/.qrust/cargo). QRUST_REAL_CARGO and compatibility.real-cargo no longer exist: a toolchain built elsewhere is used with qrust toolchain link.

7. Configuration errors apply to every command. An invalid .qrust/config.toml stops cargo --version as well as cargo build, with the field and file named; qrust upstream is unaffected.

8. No cache.mode or artifacts.gc settings. The specification’s example configuration lists them, but with remote-cache administration and GC execution out of this release each would have exactly one legal value. A read-only cache mode that a running sccache server may not honour would also be a false assurance. The keys are rejected as unknown rather than accepted and ignored.

9. Portable unit identity includes source content. Cargo hashes workspace members by their workspace-relative path, so two worktrees share unit hashes even on different branches. Cross-worktree duplicates are counted only when the inputs are identical too.

10. JSON message order is not part of the oracle. Upstream Cargo emits independent units in a different order from run to run, so the compatibility test compares the set of messages byte for byte, not their sequence.

11. Fast by default (spec revision of 2026-10-11). In the default mode = "fast", QuickRust changes what upstream Cargo would build in ways that keep program behaviour identical: debug-information settings, rustc’s parallel frontend for units compiled from scratch, a global artifact cache, and its own terminal output. mode = "compat" builds exactly upstream’s builds; the compatibility corpus’s byte-for-byte oracle tests run in compat mode, and fast mode has tests of its own (settings yield to the user, the parallel frontend never reaches an incremental rebuild, #![feature] stays rejected on a stable compiler, the cache restores correctly and never serves an edited source, fast mode and upstream keep separate artifacts instead of rebuilding each other). Every lever is measured by the speed index and checked against the benchmark workloads’ own test suites before it becomes a default.

12. RUSTC_BOOTSTRAP for -Z levers. The stable compiler contains the parallel frontend and the linker selection QuickRust uses behind -Z. QuickRust’s wrapper sets RUSTC_BOOTSTRAP=1 for the compiler processes of the units Cargo schedules, with -Zallow-features= so that #![feature] is rejected as on stable (with rustc’s “not in the list of allowed features” error instead of the stable-channel one). Never for build scripts or the compiler probes they run, so crates do not switch to nightly code paths. A nightly compiler accepts -Z flags and #![feature] anyway, so there no -Zallow-features= is added. No such lever applies when the user sets RUSTC_BOOTSTRAP themselves.

13. QuickRust’s compiler driver compiles the units Cargo schedules (fast mode, fast.early-cutoff). The driver is the toolchain’s own rustc (librustc_driver, its LLVM, its release) run through QuickRust’s callbacks, built once per toolchain against its rustc-dev component. With no callbacks active its outputs are rustc’s byte for byte (test test0276_quickrusts_compiler_driver_builds_byte_for_byte_what_rustc_builds). In fast mode three things differ from upstream’s builds, none of them in program behaviour: a library’s crate hash (SVH) is computed from what its dependents can observe, so libraries’ metadata and rlibs differ from rustc’s (the hash is an identifier; nothing compares it across compilers); outputs are linked before rustc saves its incremental state, which it finishes after Cargo has moved on; and binaries’ object files are kept (hard links next to the output) so that a binary whose own code is unchanged is linked again instead of compiled. Restored and relinked units are checked against building the same source from nothing by qrust-bench cutoff (random edits on the benchmark workloads, byte for byte; recorded in benchmarks/cutoff-gate.jsonl). Programs Cargo runs in rustc’s place (clippy-driver as a workspace wrapper, a user’s wrapper) run as they are; a crate the driver fails on is compiled by rustc.

14. No target/ in the project (decision of 2026-10-12). Upstream Cargo builds into <workspace>/target unless told otherwise; QuickRust tells it otherwise for every command: each workspace (as cargo locate-project --workspace names it) builds into ~/.qrust/cache/builds/<name>-<id>/, given to Cargo and every tool under it through CARGO_TARGET_DIR and CARGO_BUILD_BUILD_DIR, so cargo metadata reports it too. A target directory the user chose (--target-dir, --config build.target-dir, CARGO_TARGET_DIR/CARGO_BUILD_TARGET_DIR) is used as it is; build.target-dir in a Cargo configuration file is overridden. Scripts that hard-code ./target/… must ask qrust path instead. Tests: test0239_builds_go_to_quickrusts_cache_and_never_into_the_project, test0241_a_target_directory_the_user_chose_is_used…, test0242_a_build_script_building_another_workspace….

Open decisions of the specification, as resolved here