From a45783c608cbb7d508b2803e88b541a30fc3396a Mon Sep 17 00:00:00 2001 From: Cameron Date: Wed, 8 Jul 2026 22:14:24 -0700 Subject: [PATCH] Share Cargo target across worktrees Keep agent worktrees from rebuilding Bevy and other heavy dependencies into private target trees. The check gate now exports a shared target automatically, and the agent/workflow docs tell ad-hoc Cargo users to do the same. --- AGENT.md | 6 +++++ tools/check.sh | 5 ++++ tools/shared-cargo-target.sh | 46 ++++++++++++++++++++++++++++++++++++ wiki/log/DEVLOG.md | 11 +++++++++ wiki/process/workflows.md | 14 +++++++++++ 5 files changed, 82 insertions(+) create mode 100644 tools/shared-cargo-target.sh diff --git a/AGENT.md b/AGENT.md index d83f31a..9e200ab 100644 --- a/AGENT.md +++ b/AGENT.md @@ -55,6 +55,12 @@ behavior change. - **Always use a worktree.** Agent sessions do not edit the primary checkout directly. Create a task-named git worktree, work there, and keep unrelated work out of the diff. +- **Share the Cargo build cache.** After entering a worktree, run + `source tools/shared-cargo-target.sh` before ad-hoc `cargo test`, + `cargo clippy`, or Bevy build commands. `./tools/check.sh` does this + automatically. Do not let every worktree grow its own multi-GB `target/` + directory unless you deliberately need an isolated build cache; the shared + target keeps Bevy/wgpu dependency builds warm across agents. - **Commit aggressively.** Cameron has standing permission for agents to commit coherent completed work in this repository. Do not stop to ask for commit permission unless there is a pending product/design question, diff --git a/tools/check.sh b/tools/check.sh index 9e668e8..b739750 100755 --- a/tools/check.sh +++ b/tools/check.sh @@ -5,6 +5,11 @@ set -euo pipefail cd "$(dirname "$0")/.." +# Worktrees should not each rebuild Bevy/wgpu/etc. into private target trees. +# Share the primary checkout's target/ unless the caller deliberately set a +# different CARGO_TARGET_DIR. +source tools/shared-cargo-target.sh + fail=0 step() { printf '\n=== %s ===\n' "$1"; } diff --git a/tools/shared-cargo-target.sh b/tools/shared-cargo-target.sh new file mode 100644 index 0000000..4324d83 --- /dev/null +++ b/tools/shared-cargo-target.sh @@ -0,0 +1,46 @@ +#!/usr/bin/env bash +# Source this from a git worktree before long Cargo commands: +# +# source tools/shared-cargo-target.sh +# +# It points Cargo at the primary checkout's target/ directory so parallel +# worktrees reuse dependency builds instead of each compiling Bevy, wgpu, etc. +# into their own private target trees. tools/check.sh sources this +# automatically; the helper is for ad-hoc cargo test/clippy/build commands. + +misaligned_primary_checkout() { + local common + common=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 1 + + case "$common" in + */.git) + printf '%s\n' "${common%/.git}" + ;; + */.git/worktrees/*) + # Defensive fallback for git versions/configurations that report the + # per-worktree admin dir instead of the common .git directory. + printf '%s\n' "${common%%/.git/worktrees/*}" + ;; + *) + git rev-parse --path-format=absolute --show-toplevel + ;; + esac +} + +misaligned_use_shared_cargo_target() { + if [ -n "${CARGO_TARGET_DIR:-}" ]; then + return 0 + fi + + local primary target + primary=$(misaligned_primary_checkout) || return 0 + target="$primary/target" + mkdir -p "$target" + export CARGO_TARGET_DIR="$target" +} + +misaligned_use_shared_cargo_target + +if [ "${MISALIGNED_QUIET_SHARED_TARGET:-0}" != "1" ] && [ -n "${CARGO_TARGET_DIR:-}" ]; then + printf 'CARGO_TARGET_DIR=%s\n' "$CARGO_TARGET_DIR" +fi diff --git a/wiki/log/DEVLOG.md b/wiki/log/DEVLOG.md index 6f03121..4e18fa8 100644 --- a/wiki/log/DEVLOG.md +++ b/wiki/log/DEVLOG.md @@ -25,6 +25,17 @@ Reverse chronological implementation notes. Keep this factual: what changed, why hero grid; workflows note. - Checks: `./tools/site-deploy.sh`. +## 2026-07-08 - Shared Cargo target for worktrees + +- Intent: stop every agent worktree from paying the full Bevy/wgpu compile + cost into its own private `target/` tree. +- Changed: added `tools/shared-cargo-target.sh`; `tools/check.sh` now sources + it automatically; AGENT.md and workflows.md tell agents to source it before + ad-hoc Cargo commands. +- Design/spec impact: process/tooling only; no game behavior or constitution + amendment. +- Checks: `bash -n tools/shared-cargo-target.sh tools/check.sh`; `./tools/check.sh`. + ## 2026-07-08 - Splash hero is just the wordmark - Intent: no tagline on the hero — MISALIGNED is enough; pitch lives diff --git a/wiki/process/workflows.md b/wiki/process/workflows.md index 9f33f13..a3ba305 100644 --- a/wiki/process/workflows.md +++ b/wiki/process/workflows.md @@ -5,6 +5,20 @@ Type: knowledge ``` ## Build, test, verify +Worktree builds share the primary checkout's Cargo target directory. This is +what keeps Bevy/wgpu and other heavy dependencies warm across parallel agents +instead of recompiling into a fresh multi-GB `target/` in every worktree. +`./tools/check.sh` sources the helper automatically. For ad-hoc Cargo commands, +source it once in the shell first: + +```bash +source tools/shared-cargo-target.sh +``` + +If `CARGO_TARGET_DIR` is already set, the helper respects it. The default is +the primary checkout's `target/` as discovered from git's common directory, so +`.letta/`, `.claude/`, and other linked worktrees all reuse the same cache. + **One command runs the whole gate — use it before every commit:** ```bash -- 2.51.2