298bebbf

docs: the release is one tarball per OS

a73x 2026-09-04 12:50

Commit message

docs: the release is one tarball per OS

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SakwJEwD9dXBoRP5kWbemW

CLAUDE.md

Old		New
@@ -29,6 +29,8 @@ make provision-mac # clone, boot and key a macOS guest on a tart host
29	make install # the one user binary -> ~/.local/bin, ReleaseSafe	29	make install # the one user binary -> ~/.local/bin, ReleaseSafe
30	# MUX_TARGET follows the HOST: a Mac installs a Mac	30	# MUX_TARGET follows the HOST: a Mac installs a Mac
31	# binary, because that is the only one it can link	31	# binary, because that is the only one it can link
		32	make release release-mac # one tarball per OS into dist/, cut on that OS;
		33	# release-mac runs `make release` on $MAC_BUILDER
32	make xversion-build xversion # cross-version gate; XVER_OLD_WORKTREE points at the old checkout (default ..)	34	make xversion-build xversion # cross-version gate; XVER_OLD_WORKTREE points at the old checkout (default ..)
33	```	35	```
34		36

README.md

Old		New
@@ -25,9 +25,9 @@ that runs on any x86_64 Linux:
25	~/Downloads/zig-x86_64-linux-0.15.2/zig build -Dtarget=x86_64-linux-musl	25	~/Downloads/zig-x86_64-linux-0.15.2/zig build -Dtarget=x86_64-linux-musl
26	```	26	```
27		27
28	`make release` does the whole release build instead — static musl,	28	`make release` does the whole release build instead — static musl on
29	`ReleaseSafe`, stripped, checked against `build.zig`'s version, and tarred	29	Linux, `ReleaseSafe`, stripped, checked against `build.zig`'s version, and
30	into `dist/`. The tarball is what to hand another machine, because it	30	tarred into `dist/`. The tarball is what to hand another machine, because it
31	carries the exec bit that a bare downloaded binary does not:	31	carries the exec bit that a bare downloaded binary does not:
32		32
33	```sh	33	```sh
@@ -35,6 +35,19 @@ make release
35	ssh HOST 'mkdir -p ~/.local/bin && tar xzf - -C ~/.local/bin' < dist/mux-vVERSION-x86_64-linux-musl.tar.gz	35	ssh HOST 'mkdir -p ~/.local/bin && tar xzf - -C ~/.local/bin' < dist/mux-vVERSION-x86_64-linux-musl.tar.gz
36	```	36	```
37		37
		38	A release is one tarball per OS, named for the target it holds:
		39	`mux-vVERSION-x86_64-linux-musl.tar.gz` and
		40	`mux-vVERSION-aarch64-macos.tar.gz`. Each is cut on that OS — `make release`
		41	builds for the host it runs on — and both are published under
		42	`https://git.a73x.sh/mux/releases/vVERSION/`, so installing a published
		43	build is one line:
		44
		45	```sh
		46	mkdir -p ~/.local/bin
		47	curl -fsSL https://git.a73x.sh/mux/releases/vVERSION/mux-vVERSION-x86_64-linux-musl.tar.gz \| tar xzf - -C ~/.local/bin
		48	curl -fsSL https://git.a73x.sh/mux/releases/vVERSION/mux-vVERSION-aarch64-macos.tar.gz \| tar xzf - -C ~/.local/bin
		49	```
		50
38	On an Apple-silicon Mac the same build and install commands work, with two	51	On an Apple-silicon Mac the same build and install commands work, with two
39	things to install first and one binary you cannot cross-compile — see	52	things to install first and one binary you cannot cross-compile — see
40	[macOS](#macos).	53	[macOS](#macos).
@@ -728,6 +741,10 @@ make build # first build fetches + compiles the QUIC deps, as on Linu
728	make install # an aarch64 binary in ~/.local/bin	741	make install # an aarch64 binary in ~/.local/bin
729	```	742	```
730		743
		744	The Mac tarball of a release is cut by `make release-mac`, which runs
		745	`make release` on the Mac named by `MAC_BUILDER` — the same box, and the
		746	same variable, the macOS gates build on — and publishes it from there.
		747
731	`make build` runs `deps/mac-sdk.sh` first, which may build a shadow SDK	748	`make build` runs `deps/mac-sdk.sh` first, which may build a shadow SDK
732	under `deps/mac-sdk/`. Xcode 26.4 and later ship a `libSystem` stub that	749	under `deps/mac-sdk/`. Xcode 26.4 and later ship a `libSystem` stub that
733	lists only the `arm64e` slice, and the pinned Zig 0.15.2 matches the bare	750	lists only the `arm64e` slice, and the pinned Zig 0.15.2 matches the bare

docs/decisions.md

+preflight line, which is not an `ok`. The user's real Mac is no longer a
+gate target at all; it can still be `MAC_BUILDER`, which is the one role
+that touches nothing.
+## 2026-09-04 — a release is one tarball per OS, and a Mac cuts the Mac one
+`RELEASE_TARGET` now follows the host, the way `MUX_TARGET` already did.
+That reverses the rule the Makefile carried until today, which was that what
+a release IS must not follow the host that cuts it, and the reversal is
+worth stating because the old rule was right when it was written.
+It was written when there was one release, a Linux one, and it guarded
+against one accident: `MUX_TARGET` had just been hoisted to the top of the
+Makefile behind a `uname -s` switch, which put `make release` on a Mac one
+`?=` away from building a Mach-O binary and shipping it as the Linux
+tarball. What removes that danger is not the rule but the NAME. The target
+is in the filename, so a Mac cuts `mux-vN-aarch64-macos.tar.gz` and a Linux
+box cuts `mux-vN-x86_64-linux-musl.tar.gz`, and no step downstream — the
+publish, the release listing, the README's install line, `mux d upgrade`'s
+stream — can take one for the other. The old rule's second argument, that
+macOS ships no `sha256sum`, was never an argument about what a release is;
+it is a spelling, and `SHA256` is `shasum -a 256` on Darwin now.
+The reason to reverse it is that mux runs on two operating systems, and
+there is no cross-compiling the Mac binary: zig 0.15.2 asks `xcrun` for the
+SDK only for a NATIVE target, so `-Dtarget=aarch64-macos` gets no system
+include path and `@cImport` of `<util.h>` fails. So the Mac release exists
+only if a Mac cuts it. `RELEASE_BUILD_TARGET` is the second variable that
+falls out of this: `native` is the only `-Dtarget=` word that builds on a
+Mac, and `aarch64-macos` is the only name the artifact may carry, so the
+name and the build word are separate variables that happen to be the same
+string on Linux. `make release` on Linux is byte-for-byte the recipe it was.
+`make release-mac` (tools/release-mac.sh) is how the Mac tarball gets cut
+from a Linux box. It refuses unless the tag exists locally AND points at
+HEAD — a release is cut from a tag, never a branch tip — pushes exactly that
+one tag (`--no-follow-tags` and an explicit refspec: a developer with
+`push.followTags = true`, which is a common global setting, otherwise sends
+every reachable annotated tag, measured as five extra tags in the hand
+check), and then hands ONE remote shell script to `MAC_BUILDER`. That
+script fetches the tag as a tag, detaches onto it, runs `make release` and
+publishes with the builder's own `git-collab`. The publish is the builder's
+because the builder is the box holding the bytes; nothing here runs
+git-collab locally, and nothing here touches main.
+`MAC_BUILDER` has no default, and the refusal says so. A release published
+to whatever machine happened to be in someone's ssh config is worse than a
+refusal, and the variable is the same one the macOS gates take, so the
+builder is a box that is already known to build this repo.
+The builder needs three one-time arrangements beyond what the gates need,
+all of them on the builder itself: its checkout's `origin` must be the real
+remote (a gate-only checkout can have been cloned from anywhere), and it
+needs `git-collab init` and `git-collab init-key` so it has an identity to
+publish under. That key is then trusted from the developer's own box with
+`git-collab key add --global --label BUILDER`; without the trust step the
+builder's publish is refused for the identity, which reads nothing like a
+build failure.
+One outcome to expect rather than debug: a publish of a version that
+already exists is REFUSED, and that is correct. The answer is to download
+the published tarball from `https://HOST/mux/releases/vN/FILE`, extract it
+and `cmp` the BINARY against the local one — the gzip wrapper never matches,
+because it carries an mtime — and never `--force` on the strength of a
+matching sha alone. That rule was established at v0.0.1-16 (2026-08-29),
+where a publish was refused against an identical binary built 76 seconds
+earlier and the download-and-cmp is what established it was identical.