build: share compiler cache across ephemeral worktrees

[TheHypnoo]

Closes #7047

Summary

• add an opt-in Cargo wrapper for sharing compiler objects across ephemeral worktrees
• keep Cargo/sccache installation and cache storage owned by the developer environment
• document when to use cached builds versus ordinary incremental Cargo

Why

Short-lived worktrees lose local target/ reuse and repeatedly compile unchanged Rust inputs. A repository-wide wrapper or shared CARGO_TARGET_DIR would impose policy on every contributor and risk Perry's per-crate feature/link isolation, so this change provides only an explicit wrapper.

Changes

File	Change
scripts/cargo_cached.sh	Configure sccache for one Cargo invocation and forward arguments unchanged
tests/test_cargo_cached.sh	Validate defaults, overrides, argument forwarding, external cache storage, and missing tools with fake executables
docs/src/contributing/building.md	Explain ephemeral-worktree use and the long-lived incremental alternative

Validation

• shellcheck scripts/cargo_cached.sh tests/test_cargo_cached.sh
• bash -n scripts/cargo_cached.sh tests/test_cargo_cached.sh
• ./tests/test_cargo_cached.sh
• git diff --check origin/main...HEAD
• Controlled cargo check -p perry benchmark with a clean temporary target and cache

Mode	Wall time
No sccache	32.80s
Cold sccache	31.09s
Warm sccache	21.11s

The warm run served 400/400 cacheable compiler requests from cache (338 Rust, 49 C/C++, 13 assembler), with zero misses. Results are environment-specific and are not presented as a fixed speedup.

./scripts/pre-tag-check.sh --quick was also run. Its change-focused checks pass; it reports existing origin/main baseline drift in workspace architecture, benchmark freshness, file-size, GC-store, and address-classification audits. This PR does not touch any reported file or baseline.

Checklist

• Linked approved issue
• Scripts pass ShellCheck
• Documentation updated
• Conventional commit format
• No attribution trailers

Summary by CodeRabbit

• New Features
  • Added an opt-in Cargo wrapper using sccache for faster builds in ephemeral worktrees.
  • Supports configurable cache location and cache size, and routes cache to sensible defaults.
  • Automatically disables incompatible incremental compilation for cached runs.
• Documentation
  • Added guidance on using the cached wrapper, including example commands and environment-variable configuration.
• Tests
  • Added coverage for a clear failure when cache-path environment variables are missing.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1bf548a3-be8a-4462-8930-1378a44b6814

📥 Commits

Reviewing files that changed from the base of the PR and between 5bef1bb and 02636cc.

📒 Files selected for processing (2)

• scripts/cargo_cached.sh
• tests/test_cargo_cached.sh

---

📝 Walkthrough

Walkthrough

Adds an opt-in Cargo wrapper that configures sccache outside the repository, disables incremental compilation for wrapped commands, forwards arguments, validates tool availability and cache-location prerequisites, and documents usage for ephemeral worktrees.

Changes

Compiler cache workflow

Layer / File(s)	Summary
Cargo sccache wrapper scripts/cargo_cached.sh	Validates cargo and sccache, configures cache-related environment variables, reports missing cache-location prerequisites, creates the cache directory, and executes Cargo with forwarded arguments.
Wrapper behavior tests tests/test_cargo_cached.sh	Checks default settings, XDG and explicit cache overrides, argument forwarding, external cache creation, missing-tool errors, and the missing-environment failure path.
Ephemeral worktree documentation docs/src/contributing/building.md, changelog.d/7048-cargo-cache.md	Documents wrapper commands, cache configuration, disabled incremental compilation, and continued use of ordinary Cargo in long-lived worktrees.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly states the core change: adding a compiler cache wrapper for ephemeral worktrees.
Description check	✅ Passed	The description matches the template well with summary, changes, validation, and linked issue context filled in.
Linked Issues check	✅ Passed	The PR implements the requested opt-in wrapper, docs, and tests, and preserves the required behavior and constraints.
Out of Scope Changes check	✅ Passed	No unrelated code changes are evident beyond small supporting docs/test/changelog updates tied to the cache wrapper.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch build/share-compiler-cache

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/cargo_cached.sh`:
- Line 15: Update the cache-directory initialization around SCCACHE_DIR to
validate that HOME is set when neither SCCACHE_DIR nor XDG_CACHE_HOME provides a
location. Before deriving the default path, emit a clear wrapper-specific error
and exit cleanly if HOME is unavailable; preserve the existing override
precedence and default external cache location.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: bb6ae9a8-ed03-448a-9e27-5999de737049

📥 Commits

Reviewing files that changed from the base of the PR and between c5ab36b and 5bef1bb.

📒 Files selected for processing (4)

• changelog.d/7048-cargo-cache.md
• docs/src/contributing/building.md
• scripts/cargo_cached.sh
• tests/test_cargo_cached.sh