d62bdb97

build: make release, tarred, so the exec bit survives

a73x 2026-08-21 08:33

Commit message

build: make release, tarred, so the exec bit survives

Bare binaries download 0644. A fresh box then fails as 'Permission denied'
from the remote muxd, surfaced by the client as 'no endpoint announce
(UnterminatedLine)' — which names neither the file nor the mode. A tarball
carries it, and one pipe over ssh is the whole remote install.

The recipe was living in a memory of how the last release was built. It
now checks the stripped artifacts' own --version against build.zig, which
is the failure a hand-run recipe actually has: a stale stage directory
shipping under a bumped number.

Makefile

@@ @@ -2,7 +2,7 @@ @@
+# default zig is 0.17-dev. Override with ZIG=... if yours lives elsewhere.
+ZIG ?= $(HOME)/Downloads/zig-x86_64-linux-0.15.2/zig
+.PHONY: build test e2e soak bench agent deps clean clean-deps xversion xversion-build install release
+# The QUIC stack (deps/quic) is built on demand by build.zig, so no target
+# here needs to depend on this one. It exists to make the one-time cost
@@ @@ -24,6 +24,46 @@ install: build @@
+	install -d $(BINDIR)
+	install -m755 zig-out/bin/muxd zig-out/bin/mux zig-out/bin/muxa zig-out/bin/muxweb $(BINDIR)/
+# The artifact a release publishes, built the way every release since
+# v0.0.1-4 has been: static musl so one binary runs on any x86_64 Linux,
+# ReleaseSafe because the safety checks are worth more than the last few
+# percent and they survive stripping — only DWARF goes, 17MB to ~3MB each.
+#
+# TARRED, and that is the point of having a target at all. Publishing the
+# four binaries bare loses the exec bit: they download 0644, and the first
+# thing anyone does on a fresh box is a chmod nothing documents. A tarball
+# carries the mode, so `tar xzf - -C ~/.local/bin` over ssh is the whole
+# remote install.
+#
+# Flat rather than a versioned directory inside, for the same reason: the
+# common move is putting muxd on a box, and one pipe should finish it.
+VERSION := $(shell sed -n 's/^[[:space:]]*const version = "\(.*\)";/\1/p' build.zig | head -1)
+RELDIR ?= dist
+RELBIN = $(RELDIR)/v$(VERSION)
+RELTAR = $(RELDIR)/mux-v$(VERSION)-x86_64-linux-musl.tar.gz
+# The version guard below asks the STRIPPED artifacts what they are, so a
+# stale stage directory cannot ship under a bumped number. muxa has no
+# --version (it is verbs and JSON), so it is built and shipped but not asked.
+release:
+	@test -n "$(VERSION)" || { echo "release: no version found in build.zig"; exit 1; }
+	$(ZIG) build -Dtarget=x86_64-linux-musl -Doptimize=ReleaseSafe -p $(RELDIR)/stage
+	rm -rf $(RELBIN) $(RELTAR)
+	install -d $(RELBIN)
+	install -m755 $(RELDIR)/stage/bin/muxd $(RELDIR)/stage/bin/mux \
+		$(RELDIR)/stage/bin/muxa $(RELDIR)/stage/bin/muxweb $(RELBIN)/
+	strip $(RELBIN)/muxd $(RELBIN)/mux $(RELBIN)/muxa $(RELBIN)/muxweb
+	@for b in muxd mux muxweb; do \
+		got=$$($(RELBIN)/$$b --version | awk '{print $$2}'); \
+		[ "$$got" = "$(VERSION)" ] || { \
+			echo "release: $$b reports $$got, expected $(VERSION)"; exit 1; }; \
+	done
+	tar czf $(RELTAR) -C $(RELBIN) muxd mux muxa muxweb
+	@echo
+	@sha256sum $(RELTAR)
+	@echo "install:  tar xzf $(RELTAR) -C ~/.local/bin"
+	@echo "remote:   ssh HOST 'mkdir -p ~/.local/bin && tar xzf - -C ~/.local/bin' < $(RELTAR)"
+	@echo "publish:  git collab release publish v$(VERSION) $(RELTAR)"
+test:
+	$(ZIG) build test

README.md

Old		New
@@ -25,6 +25,16 @@ 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,
		29	`ReleaseSafe`, stripped, checked against `build.zig`'s version, and tarred
		30	into `dist/`. The tarball is what to hand another machine, because it
		31	carries the exec bit that a bare downloaded binary does not:
		32
		33	```sh
		34	make release
		35	ssh HOST 'mkdir -p ~/.local/bin && tar xzf - -C ~/.local/bin' < dist/mux-vVERSION-x86_64-linux-musl.tar.gz
		36	```
		37
28	## Quick start, local	38	## Quick start, local
29		39
30	```sh	40	```sh

docs/decisions.md

+it, and a local session needs `-A` where it previously needed nothing. The
+overwrite is the point — otherwise every client shares one identity — but it
+is a regression for one workflow and is now documented as one.
+**Releases are tarred, and `make release` is why there is a rule.** From
+v0.0.1-4 through v0.0.1-10 a release was one `mux-vX-x86_64-linux-musl.tar.gz`;
+v0.0.1-11 published the four binaries bare, with no decision recorded anywhere
+and nothing in the repo consuming either shape. The bare form costs the exec
+bit — a downloaded binary arrives 0644, so `mux HOST` on a freshly installed
+box dies with `Permission denied` from the remote `muxd` and reports it as
+`no endpoint announce (UnterminatedLine)`, which names neither the file nor
+the mode. Observed on a LAN box the day v0.0.1-12-pre1 went out.
+So: tar, flat, one `tar xzf - -C ~/.local/bin` over ssh to install, and the
+recipe lives in the Makefile rather than in a memory of how the last one was
+built. The target asks the STRIPPED artifacts their `--version` and refuses
+to ship if it disagrees with `build.zig` — a stale stage directory under a
+bumped number is the failure a hand-run recipe actually has. The binaries are
+reproducible (a rebuild matched the published sha256s byte for byte); the
+gzip wrapper is not, since it embeds an mtime.