feat(build): --size, a mode that optimises for artifact bytes (#1729)

[paul-hammant]

Closes #1729. From an ask by the html-sanitizer downstream, whose other half merged as #1728.

The root cause was not where we thought

Both the ask and #1729 said "something in the zig cross path is adding -g — or not passing whatever suppresses it." It's the second, and it isn't ours:

zig cc emits DWARF by default, even at -O2. Confirmed directly on one translation unit:

zig cc -target wasm32-wasi -O2      -c d.c -o d1.o   →  1,349 bytes
zig cc -target wasm32-wasi -O2 -g0  -c d.c -o d2.o   →    477 bytes

Nothing in ae_cross.c was adding -g — the optimised path is a bare "-O2". We simply never passed -g0, and zig's default filled the gap.

The fix

ae build --size: -Oz -g0 at compile, -Wl,--strip-all -Wl,--gc-sections at link.

	bytes
--target=wasm32-wasi --emit=lib	956,573
…--size	24,942

38×, and behaviourally identical — the 24 KB module instantiates under node's WASI, exports every symbol, and still traps correctly on the fail-stop panic path from #1728:

risky(21) = 42 (want 42)
safe(21)  = 42 (want 42)
safe(-1)  -> trapped: RuntimeError (fail-stop, as designed)

That lands almost exactly on the ask's hand-stripped figure, which is the sanity check I wanted: we're recovering what stripping recovers, not accidentally dropping something else.

Two deliberate limits

Not the default. A 38× difference is discoverable — anyone shipping to a browser will find the flag — whereas stripping every build by default would make the first "why can't I get a stack trace from my wasm module" report genuinely hard to diagnose. Named modes keep the trade-off visible at the point of choosing it. (This was the opinion I gave in #1729; happy to be overruled.)

No link-time stripping for --emit=obj / --emit=csrc. Neither links, and an object file's symbols are precisely what whoever links it next needs. They still get -Oz -g0 for the compile. Tested — nm still finds the symbols in a --emit=obj --size output.

--profile wins if both are passed: asking for a small artifact and a profileable one is contradictory, and the debug-oriented reading is safer. Same precedence shape --coverage already has over --profile.

A trap worth knowing about

tools/ae.c has a second optimisation-flag path — base_opt at line 2530 — that bypasses opt_flags() and carries its own "Keep this in sync" comment. --size had to be added to both. Had I only done opt_flags(), the mode would have silently done nothing on the path build_gcc_cmd takes, and the native half of the test would have passed anyway because the cross path is separate again.

What I chose not to do

The ask offered --cflags=/--ldflags= passthrough as an alternative. I went with the named mode because a passthrough makes the toolchain's flag surface part of our public contract by accident, and "what does ae pass by default" becomes something users must reverse-engineer to know what they're overriding. The mode is also discoverable in ae build's usage output, which a passthrough isn't.

Verification

• make test: 394 passed, 0 failed
• New tests/integration/size_mode/, asserting in rising order of what would actually break a user: the binary runs; --emit=lib keeps its dynamic symbols (a stripped library with none links fine and is useless); --emit=obj keeps its symbols; the wasm artifact is dramatically smaller and still a valid module with its exports intact. The size assertion is a conservative 4× against a measured 38×, so a partial regression — say -g0 lost but stripping kept — still trips it.
• Fixture added to tests/ae_sweep_prune.txt (no main), and the prune verified rather than assumed.
• make check-docs clean; --size documented in docs/build-system.md beside --profile, and added to ae build's usage text.

🤖 Generated with Claude Code