rust-build

rust-build

Cross-worktree cache reuse wants a shared target dir; correctness wants isolation. scripts/rust-build.sh resolves it — share by default, isolate automatically only when a worktree diverges a crate other crates link.

Use it

Drop-in for cargo, from any worktree (or the main tree):

scripts/rust-build.sh build -p nub-cli --profile fast
scripts/rust-build.sh test  -p nub-cli --test integration
NUB_ALLOW_INCOMPLETE_RUNTIME=1 scripts/rust-build.sh clippy --all-targets --all-features -- -D warnings

That third line needs a staged runtime/ first, and opts out of the vendored-deps half because a lint ships nothing. The "--all-features needs a staged addon AND the vendored runtime deps" section below has the placeholder recipe and the two failure modes.

It prints which target dir it chose and why, then execs cargo with CARGO_TARGET_DIR set. Two default-on contention controls ride along:

• QoS clamp (darwin only): cargo runs under taskpolicy -c utility, so interactive work preempts fleet builds; an uncontended build still gets all cores. NUB_BUILD_FG=1 opts out.
• Job cap on big hosts (>8 cores): CARGO_BUILD_JOBS = ncpu-4 unless the caller already chose (pre-set CARGO_BUILD_JOBS, NUB_BUILD_JOBS, or an explicit -j/--jobs — cargo's flag outranks the env var).

These cover builds going THROUGH the wrapper (or make). Direct cargo invocations are clamped by a machine-global control: make qos-global installs scripts/rustc-qos.sh as the cargo rustc-wrapper in ~/.cargo/config.toml, so every rustc on the host compiles at utility QoS, at most TWO builds compile at a time (the rest queue first-come-first-served; make build-status shows the holders and the queue), and the compiling builds share NUB_RUSTC_LIMIT (default 6) rustc tokens (install-dev re-runs it, so it self-heals). NUB_BUILD_FG=1 opts a HUMAN's foreground build out of the clamp and the queue (and, through this wrapper, out of the tokens too) — never set it from an agent; NUB_BUILD_SLOTS=0 in a build's environment disables only the slot layer for that build. Toggling any of these does not invalidate fingerprints. Details: the rust-build-hygiene skill.

Why one shared target dir

All worktrees default to ~/.cache/nub/shared-target. A fresh worktree reuses the crates.io dependency rlibs a sibling already compiled and recompiles only the ~3 workspace crates — ~5s instead of a ~3-min cold build.

Relocation does NOT defeat reuse. Cargo revalidates a relocated target dir in place: cloning a warm dir to a new path rebuilt 0 crates; an empty dir rebuilt all 13. (The "path is baked into fingerprints" claim is true of sccache, which keys on the rustc command line including absolute --out-dir / -L dependency= paths — not of cargo.) So sharing a live path buys convergence; a CoW clone buys a warm start, which is why the wrapper seeds a fresh private dir from the matching bucket instead of cold-starting.

The hazard sharing creates

Cargo names a crate's output by package id (name + version), not source content. Two worktrees whose source for the same depended-on crate differs — classically vendor/aube on divergent branches — write the same output slot and clobber each other. A dependent crate then links the stale rlib:

error[E0063]: missing field `lockfile_legacy_basenames` in initializer of `aube_util::Embedder`

— a field that exists nowhere in your checkout. Only bites crates that other crates link; a divergent leaf binary (nub-cli) just rebuilds cleanly.

The rule the wrapper enforces