ea607659
docs: align toolchain instructions with mise
a73x 2026-09-09 05:52
Commit message
CLAUDE.md
| Old | New | ||
|---|---|---|---|
| @@ -16,7 +16,10 @@ edits do not require that workflow. | |||
| 16 | 16 | ||
| 17 | ## Toolchain and gates | 17 | ## Toolchain and gates |
| 18 | 18 | ||
| 19 | Use `deps/zig/zig` (0.15.2) through Make; the system Zig is incompatible. | 19 | Use `mise` (pinned to Zig 0.15.2 in `mise.toml`) through Make; Make resolves |
| 20 | `ZIG` via `mise which zig` and respects an explicit `ZIG=/path/to/zig` | ||
| 21 | override. `mise install` provisions this compiler per machine; worktrees reuse | ||
| 22 | it, so `deps/zig` is not required. The system Zig is incompatible. | ||
| 20 | Make handles the macOS shadow SDK. See [development commands](docs/development.md) | 23 | Make handles the macOS shadow SDK. See [development commands](docs/development.md) |
| 21 | for setup, releases, cross-OS checks and the full command list. | 24 | for setup, releases, cross-OS checks and the full command list. |
| 22 | 25 | ||
docs/component-ownership.md
| Old | New | ||
|---|---|---|---|
| @@ -57,12 +57,16 @@ semantics, or the meaning of an error shared across frontends. | |||
| 57 | 57 | ||
| 58 | Start from the current checkout and read `CLAUDE.md`, the relevant component | 58 | Start from the current checkout and read `CLAUDE.md`, the relevant component |
| 59 | header, and the affected contract or protocol comments. Use an isolated | 59 | header, and the affected contract or protocol comments. Use an isolated |
| 60 | worktree when another component is active, after ensuring its ignored pinned | 60 | worktree when another component is active, after ensuring its pinned toolchain |
| 61 | toolchain (`deps/zig`) and generated dependency inputs (`deps/quic/out` and | 61 | (via `mise install` for the Zig pin in `mise.toml`) is available. The QUIC |
| 62 | `deps/quic/work`) are available. The QUIC build script itself is tracked. | 62 | build script itself is tracked. |
| 63 | Use worktree-local generated dependencies when rebuilding them; do not run | 63 | Use worktree-local generated dependencies when rebuilding them; if another |
| 64 | concurrent builders or cleanup against shared dependency directories. Build | 64 | worktree at the same revision/platform has matching `deps/quic/out`, you can |
| 65 | with the pinned toolchain through Make so macOS SDK setup is retained. For | 65 | copy it in to avoid re-downloading, but keep `deps/quic/work` local per-worktree. |
| 66 | That workspace | ||
| 67 | contains absolute-path build caches and should not be shared by mutable symlinks. | ||
| 68 | Do not run concurrent builders or cleanup against shared dependency directories. | ||
| 69 | Build with the pinned toolchain through Make so macOS SDK setup is retained. For | ||
| 66 | example, a daemon task can use: | 70 | example, a daemon task can use: |
| 67 | 71 | ||
| 68 | ```sh | 72 | ```sh |
docs/development.md
| Old | New | ||
|---|---|---|---|
| @@ -1,12 +1,11 @@ | |||
| 1 | # Development commands | 1 | # Development commands |
| 2 | 2 | ||
| 3 | ```sh | 3 | ```sh |
| 4 | ZIG=deps/zig/zig # vendored 0.15.2 (ghostty pin); copy the toolchain here, gitignored | 4 | mise install # install/pin Zig 0.15.2 from mise.toml; one host install is shared across worktrees |
| 5 | # on a Mac that is the aarch64 0.15.2 tarball, in the same place | ||
| 6 | make mac-sdk # Darwin only, and `make build` runs it: a shadow SDK | 5 | make mac-sdk # Darwin only, and `make build` runs it: a shadow SDK |
| 7 | # under deps/mac-sdk, because zig 0.15.2 cannot link | 6 | # under deps/mac-sdk, because zig 0.15.2 cannot link |
| 8 | # the stub Xcode 26.4+ ships. No-op elsewhere. | 7 | # the stub Xcode 26.4+ ships. No-op elsewhere. |
| 9 | make build test e2e # build lints first; Makefile already points at the pinned Zig | 8 | make build test e2e # build lints first; Makefile resolves ZIG via mise (or `ZIG=/path/to/zig`) |
| 10 | make lint # standalone: fetch/verify pinned zlint and lint Zig sources | 9 | make lint # standalone: fetch/verify pinned zlint and lint Zig sources |
| 11 | make check # lint + fmt + tests + shell/web ABI/source checks — pre-commit gate | 10 | make check # lint + fmt + tests + shell/web ABI/source checks — pre-commit gate |
| 12 | make ci # check + e2e + agent + throughput — the delivery gate | 11 | make ci # check + e2e + agent + throughput — the delivery gate |
| @@ -33,7 +32,13 @@ make xversion-build xversion # cross-version gate; XVER_OLD_WORKTREE points at | |||
| 33 | ``` | 32 | ``` |
| 34 | 33 | ||
| 35 | First build after a clean checkout fetches ~30MB of QUIC deps (minutes, once). | 34 | First build after a clean checkout fetches ~30MB of QUIC deps (minutes, once). |
| 36 | `make clean` deliberately spares `deps/quic`. | 35 | `deps/quic/out` holds the generated link-time outputs; `deps/quic/work` is the |
| 36 | local build workspace and cache. In multi-worktree workflows, you can copy a | ||
| 37 | same-revision/same-platform `deps/quic/out` tree from another worktree to avoid | ||
| 38 | re-downloading, but keep `deps/quic/work` local per-worktree: it contains | ||
| 39 | absolute-path build caches and should not be shared via mutable symlinks. | ||
| 40 | `make clean-deps` removes `deps/quic/out` and `deps/quic/work`; `make clean` | ||
| 41 | deliberately spares `deps/quic`. | ||
| 37 | 42 | ||
| 38 | ## Lint dependencies | 43 | ## Lint dependencies |
| 39 | 44 | ||