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 locations and sizes with sensible defaults.
  • Automatically disables incompatible incremental compilation for cached runs.
  • Provides a clear error when no cache location can be determined.
• Documentation
  • Added guidance, example commands, and environment-variable configuration for the cached wrapper.
• Tests
  • Added coverage for cache configuration and failure handling.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 1e99593f-710e-433f-92ac-249e811b10dc

📥 Commits

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

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (3)

• CLAUDE.md
• Cargo.toml
• changelog.d/7048-cargo-cache.md

---

📝 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 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.
Usage documentation and release metadata docs/src/contributing/building.md, changelog.d/7048-cargo-cache.md, CLAUDE.md, Cargo.toml	Documents wrapper usage and cache behavior, and updates the project version to 0.5.1266.

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

Possibly related PRs

• PerryTS/perry#6751: Introduces the per-PR changelog workflow used by this change.

Suggested labels: tooling

Suggested reviewers: proggeramlug

🚥 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 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