From 41b5169a52df41cf2a53dbe917440bfefd26ff67 Mon Sep 17 00:00:00 2001 From: dlovell Date: Sun, 31 May 2026 13:29:25 +0000 Subject: [PATCH] docs: add overlay creation guidance Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 2 ++ projects/README.md | 22 ++++++++++++++++++++++ 2 files changed, 24 insertions(+) create mode 100644 projects/README.md diff --git a/CLAUDE.md b/CLAUDE.md index a3a4fc9..9de19c7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -41,3 +41,5 @@ bash tests/test-resolve-list-cleanup.sh - Python targets 3.12, formatted by ruff with 120 char line length (see `ruff.toml`). - Commit messages follow conventional commits: `fix:`, `feat:`, `ci:`, etc. - `.gitignore.template` defines patterns for per-worktree gitignored files; `setup-worktree` copies it as `.gitignore` into each worktree. +- When targeting a specific dependency group, use `uv sync --group dev`, not `--dev` (legacy alias removed in uv 0.7.x+). +- When creating a new project overlay, strip inherited packages and config for tools the target project doesn't use — don't leave dead weight from the source overlay. diff --git a/projects/README.md b/projects/README.md new file mode 100644 index 0000000..26f298f --- /dev/null +++ b/projects/README.md @@ -0,0 +1,22 @@ +# Project overlays + +Each subdirectory is a project-specific overlay applied on top of the base devcontainer image. See `defaults/` for the fallback overlay and file-by-file documentation. + +## Creating a new overlay + +Start from the closest existing overlay, not `defaults/`. The volume topology, toolchain pinning, and SHA256 checksums are easy to get wrong from scratch — stripping what you don't need is faster and less error-prone. + +### Cargo volumes + +Rust overlays use a three-volume split: + +- `cargo-registry` and `cargo-git` — shared across worktrees (`external: true`). These are content-addressed and safe to share. +- `cargo-target` — per-worktree (no `external: true`). Concurrent writes to a shared target dir corrupt incremental build state. + +Shared volumes must be listed in `external-volumes.txt` so `ensure_external_volumes()` pre-creates them before compose up. Missing an entry here means the first `devcontainer up` fails with a missing-volume error. + +The `cargo-target` mount point must match where the crate root is. For example, `xorq-desktop` mounts it at `desktop/src-tauri/target` while `batchcorder` mounts at the repo-root `target/`. Getting this wrong means builds write to the wrong place. + +### Expensive build steps + +Gate expensive build steps (e.g., `maturin develop`) behind artifact presence checks so container recreation with persisted volumes doesn't pay for a redundant rebuild. Use file-presence tests (`compgen -G "path/*.so"`) rather than import probes, which can trigger the build tool and defeat the skip.