@amritk/nish 0.10.0

package/scripts/bootstrap.sh

@@ -0,0 +1,357 @@
+#!/usr/bin/env bash
+# Build the self-hosted compiler: `self/`, compiled by `self/`.
+#
+#   scripts/bootstrap.sh [-o <exe>] [--stages 1|2|3] [--profile speed|size|debug]
+#                        [--work <dir>] [--verify] [--quiet]
+#
+# The chain is the one docs/wp14-selfhost.md §1 defines, with the seed as a
+# parameter rather than a fixture (docs/wp19-stage0-retirement.md §3, G3):
+#
+#   seed     whatever compiles stage1              NISH_BOOTSTRAP, or build/seed
+#   stage1   self/, built by the seed
+#   stage2   self/, built by stage1                the default output
+#   stage3   self/, built by stage2                --verify only
+#
+# NISH_BOOTSTRAP=<path> names the seed, the way GOROOT_BOOTSTRAP names the Go
+# that builds Go. It is either a released `nish`, executed directly, or a Node
+# entry point (`.js`, `.mjs`, `.cjs`) wrapping one, executed as `node <path>`:
+#
+#   NISH_BOOTSTRAP=~/nish-0.6.0-linux-x86_64 scripts/bootstrap.sh --verify
+#
+# Unset, the seed is build/seed/bin/nish, the last release as
+# `scripts/fetch-seed.sh` unpacks it, and this runs that script first. When the
+# fetch fails it stops and says so: a compiler has to come from somewhere, and
+# the only place left is a release.
+#
+# stage2 is what this installs, because it is the first binary in the chain
+# that no part of the seed emitted: the seed built the compiler that built it,
+# and `--verify` is what says the two agree. `--stages 1` stops at the seed's
+# own output, which is enough to *use* the self-hosted compiler and half the
+# wait.
+#
+# --verify runs the equalities the proof is made of, byte for byte:
+#
+#   IR(seed, self/)   == IR(stage1, self/)     reported, never asserted
+#   IR(stage1, self/) == IR(stage2, self/)     the fixed point: self-hosted
+#   stage3 == stage2                           as files, on ELF and on Mach-O
+#                                              alike; see below for what the
+#                                              Mach-O half took
+#
+# The last two are properties of the working tree and of nothing else: whatever
+# built stage1, the compiler `self/` describes has to agree with itself and
+# then reproduce itself. Both are asserted whatever the seed is.
+#
+# The third is a raw byte comparison, and on Mach-O two links of the same input
+# did not produce the same bytes -- measured, at identical size, with every IR
+# equality green (WP19 R2). WHICH bytes is measured too now, and so is what they
+# vary with: LC_UUID, stable across two links to one output path and differing
+# on a link to another, plus on arm64 the one code-directory slot that hashes
+# the page it sits on. That is why `link_stage` below builds every comparable
+# stage at one path, and with it the comparison holds as raw bytes on Mach-O as
+# well -- measured end to end, whatever the UUID turns out to be a function of.
+# Under that, on Darwin only, the script
+# still asserts the size, strips what it can, and reports anything left over as
+# *unattributed* rather than as a compiler difference -- narrower than raw bytes
+# and wider than an exemption, which would accept a stage3 that is a different
+# compiler. The comparison and the reasoning live in
+# `scripts/verify-binaries.sh` -- a script rather than a block in here so that
+# `tests/run.js` can drive both platforms' branches -- and its header has the
+# measurement, byte offsets and all.
+#
+# The first one is reported and not asserted. With a released seed it is one
+# implementation at two points in time: the IR HEAD emits for `self/` is the
+# IR the last release emitted for it. Nothing in that sentence is about
+# bootstrapping. It is a freeze on codegen between releases, and it fails on
+# exactly the changes a release cycle exists to carry: the first improvement to
+# land broke it, when a flow-sensitive bounds analysis proved 46 of `self/`'s
+# 1,206 index checks redundant and 20 of 56 modules "differed" because the
+# optimisation worked. So the difference is reported, and the report is
+# information about this release rather than a verdict on the bootstrap.
+#
+# While `src/` existed, a stage0 seed made the same comparison the second half
+# of Wheeler's diverse double-compiling, and it was asserted there
+# (docs/wp19-stage0-retirement.md §1, G6). That claim went with `src/`.
+#
+# What the seeded run buys is not that equality. The rolling freeze — "a
+# construct added in 0.N cannot be used by `self/` until 0.(N+1)" — is enforced
+# by stage1 being built at all: a `self/` that reaches for something the seed
+# has never heard of does not compile, does not link, and never gets as far as
+# a comparison. That failure is loud here whatever the seed is, and it is the
+# whole of what the seeded run proves about the freeze
+# (docs/wp19-stage0-retirement.md §3, G3).
+#
+# `node tests/self/bootstrap.js` is the same check with the suite's reporting,
+# and is what CI runs; this script is how the compiler gets built for use.
+#
+# The result is a complete compiler: it plans its own output, makes the
+# directories and links through `scripts/build.sh` itself, so nothing has to
+# stand between it and a build (docs/wp14-selfhost.md §7a).
+#
+# Needs a runnable seed, and clang + lld on PATH for the links
+# (docs/INSTALL.md).
+set -euo pipefail
+
+# Read the seed before the `cd` below moves us: a relative NISH_BOOTSTRAP is
+# relative to the directory the caller typed it in, not to the repository root.
+seed_given="${NISH_BOOTSTRAP:-}"
+case "$seed_given" in
+  ""|/*) ;;
+  *) seed_given="$PWD/$seed_given" ;;
+esac
+
+cd "$(dirname "$0")/.."
+
+out=build/nish
+work=build/selfhost
+profile=speed
+stages=2
+verify=0
+quiet=0
+
+usage() {
+  cat <<'EOF'
+usage: scripts/bootstrap.sh [-o <exe>] [--stages 1|2|3] [--profile speed|size|debug]
+                            [--work <dir>] [--verify] [--quiet]
+
+Builds the self-hosted compiler. The seed builds stage1, stage1 builds stage2
+(the default output), stage2 builds stage3. --verify compares the IR each stage
+emits for self/ and the stage2/stage3 binaries, byte for byte. The result is
+the command line itself: -o, --link, --profile and the rest.
+
+IR(seed) == IR(stage1) asks whether codegen has changed since the seed was
+built, so it is reported and not asserted; IR(stage1) == IR(stage2) and
+stage3 == stage2 are asserted whatever the seed is.
+
+The seed is NISH_BOOTSTRAP=<path> when it is set — a released `nish` binary, or
+a .js/.mjs entry point run under node — and build/seed/bin/nish, the release
+scripts/fetch-seed.sh unpacks, when it is not:
+
+  scripts/bootstrap.sh
+  NISH_BOOTSTRAP=~/nish-0.6.0-linux-x86_64 scripts/bootstrap.sh --verify
+EOF
+  exit "${1:-2}"
+}
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -o|--output) out="${2:-}"; [ -n "$out" ] || usage; shift 2 ;;
+    --work) work="${2:-}"; [ -n "$work" ] || usage; shift 2 ;;
+    --profile) profile="${2:-}"; [ -n "$profile" ] || usage; shift 2 ;;
+    --stages) stages="${2:-}"; shift 2 ;;
+    --verify) verify=1; shift ;;
+    --quiet) quiet=1; shift ;;
+    -h|--help) usage 0 ;;
+    *) echo "bootstrap: unknown argument \`$1\`" >&2; usage ;;
+  esac
+done
+
+case "$stages" in
+  1|2|3) ;;
+  *) echo "bootstrap: --stages takes 1, 2 or 3 (got \`$stages\`)" >&2; exit 2 ;;
+esac
+# `--stages` says which compiler to install; verifying the fixed point needs
+# the stage that closes it built as well, whether or not it is the one kept.
+install=$stages
+build_to=$stages
+[ "$verify" -eq 1 ] && build_to=3
+
+# The published npm package ships bin/, runtime/, scripts/ and std/ but not
+# self/ -- and, since 0.6.0, no compiler of its own at all -- so say which file
+# is missing rather than failing inside the compiler.
+if [ ! -f self/compile.ts ]; then
+  echo "bootstrap: self/compile.ts is missing; run this from a checkout of the repository" >&2
+  exit 3
+fi
+
+# One place that knows how to invoke the seed, so every stage below reads the
+# same whichever kind of seed ran.
+run_seed() {
+  if [ "$seed_kind" = node ]; then
+    node "$seed" "$@"
+  else
+    "$seed" "$@"
+  fi
+}
+
+seed_die() {
+  echo "bootstrap: $seed_origin $seed $1" >&2
+  echo "bootstrap: the seed is a released \`nish\` binary, or a .js/.mjs entry point run under node" >&2
+  exit 3
+}
+
+# Unset: the release scripts/fetch-seed.sh leaves in build/seed, fetched
+# first when it is not there (a no-op, without the network, when it is).
+if [ -z "$seed_given" ]; then
+  if ! sh scripts/fetch-seed.sh >&2 || [ ! -e build/seed/bin/nish ]; then
+    echo "bootstrap: no seed: NISH_BOOTSTRAP is unset and scripts/fetch-seed.sh could not" >&2
+    echo "bootstrap: fetch the last release into build/seed; set NISH_BOOTSTRAP=<nish>" >&2
+    exit 3
+  fi
+  seed_given="$PWD/build/seed/bin/nish"
+  seed_origin="the released seed"
+else
+  seed_origin="NISH_BOOTSTRAP seed"
+fi
+seed=$seed_given
+# The kind is decided by the extension, and deliberately not by the
+# executable bit or by sniffing the bytes. The bit describes the download
+# rather than the file — a binary unpacked from a release tarball or pulled
+# out of a CI artifact can arrive without +x —
+# whereas the suffix is the one thing whoever built the seed chose. Anything
+# with no suffix is a binary, which is how a released `nish` arrives.
+case "$seed" in
+  *.js|*.mjs|*.cjs) seed_kind=node; seed_label="$seed_origin (node $seed)" ;;
+  *) seed_kind=native; seed_label="$seed_origin ($seed)" ;;
+esac
+[ -e "$seed" ] || seed_die "does not exist"
+[ -f "$seed" ] || seed_die "is not a file"
+if [ "$seed_kind" = native ]; then
+  [ -x "$seed" ] || seed_die "is not executable"
+else
+  [ -r "$seed" ] || seed_die "is not readable"
+  command -v node >/dev/null 2>&1 || seed_die "needs node on PATH, which is not there"
+fi
+# A seed that cannot answer `--version` cannot compile self/ either — a
+# binary built for another platform, a .js that is not a compiler — and
+# finding that out here names the variable and the path the caller set, where
+# finding it out in the stage1 link names a temporary file three stages deep.
+run_seed --version >/dev/null 2>&1 || seed_die "is not runnable (\`--version\` failed)"
+if ! command -v clang >/dev/null 2>&1 && [ -z "${CC:-}" ]; then
+  echo "bootstrap: needs clang on PATH to link the stages (see docs/INSTALL.md)" >&2
+  exit 3
+fi
+
+say() { [ "$quiet" -eq 1 ] || printf '%s\n' "$*"; }
+
+# `a` and `b` hold one `.ll` per module of `self/`. Both the module set and
+# every byte of every module must match: a stage that emitted one module fewer
+# has not agreed about the rest.
+compare_ir() {
+  local a="$1" b="$2" label="$3" name
+  if ! diff <(cd "$a" && ls ./*.ll) <(cd "$b" && ls ./*.ll) >/dev/null; then
+    echo "bootstrap: $label: the two stages emitted different module sets" >&2
+    exit 1
+  fi
+  for name in "$a"/*.ll; do
+    if ! cmp -s "$name" "$b/$(basename "$name")"; then
+      echo "bootstrap: $label: $(basename "$name") differs" >&2
+      diff "$name" "$b/$(basename "$name")" | head -n 20 >&2
+      exit 1
+    fi
+  done
+  say "  $label: $(ls "$a"/*.ll | wc -l | tr -d ' ') modules identical"
+}
+
+# IR(seed) vs IR(stage1), reported and never asserted. What it measures is
+# whether codegen has moved since the seed was built, which is a fact about
+# this release rather than a property of the bootstrap — the header says why.
+# Nothing in here exits.
+survey_ir() {
+  local a="$1" b="$2" total=0 differing=0 name
+  if ! diff <(cd "$a" && ls ./*.ll) <(cd "$b" && ls ./*.ll) >/dev/null; then
+    say "  note: IR(seed) vs IR(stage1): the two emitted different module sets."
+    say "        Not a bootstrap failure: this comparison is not asserted"
+    say "        (see the header of this script)."
+    return 0
+  fi
+  for name in "$a"/*.ll; do
+    total=$((total + 1))
+    cmp -s "$name" "$b/$(basename "$name")" || differing=$((differing + 1))
+  done
+  if [ "$differing" -eq 0 ]; then
+    say "  note: IR(seed) vs IR(stage1): all $total modules identical."
+    say "        Not asserted: codegen simply has not moved for self/ since"
+    say "        the seed was built."
+  else
+    say "  note: IR(seed) vs IR(stage1): $differing of $total modules differ."
+    say "        Not a bootstrap failure. Codegen has moved for self/ since the"
+    say "        seed was built, which is what a release carries. See the header"
+    say "        of this script and docs/wp19-stage0-retirement.md §3, G3."
+  fi
+}
+
+# Build one stage with another, at a path every stage shares, and move it into
+# place afterwards.
+#
+# The shared path is what makes `stage3 == stage2` hold on Mach-O, and it is
+# measured rather than tidy-mindedness: LC_UUID is stable across two links to
+# one output path and differs on a link to another. Two links of one input to
+# one path produce one UUID and byte-identical files; the same two to `.../one`
+# and `.../two` differ in exactly those sixteen bytes. So stage2 at
+# `$work/stage2` and stage3 at `$work/stage3` gave two different UUIDs to two
+# compilers that had agreed about every other byte, and the comparison could
+# only ever report that as unattributed. The output path is the leading reason
+# and the probe cannot rule out an invocation counter -- docs/wp10-ci.md#ci-matrix
+# has that, the offsets, and the remedy that did not work -- but the shared path
+# was measured to work end to end either way, and build.sh's Darwin branch says
+# why the flag that drops the load command is not the answer.
+#
+# It costs one rename per stage and weakens nothing: the comparison is still a
+# raw `cmp` of the two files.
+#
+# stage1 is left out because nothing compares it to a binary -- `IR(seed) ==
+# IR(stage1)` compares the .ll files its build wrote, and those are the same
+# bytes wherever the executable landed.
+link_stage() {
+  local by="$1" name="$2"
+  rm -rf "$work/stage" "$work/stage.modules"
+  "$by" self/compile.ts --link "$work/stage" --profile "$profile" >/dev/null
+  rm -rf "$work/$name" "$work/$name.modules"
+  mv "$work/stage" "$work/$name"
+  mv "$work/stage.modules" "$work/$name.modules"
+}
+
+mkdir -p "$work"
+outdir=$(dirname "$out")
+[ "$outdir" = "" ] || mkdir -p "$outdir"
+
+# Every stage is built the same way, by the stage before it, with one
+# `--link`: the compiler plans the output, makes `<exe>.modules/` and runs
+# `scripts/build.sh` itself (docs/wp14-selfhost.md §7a). That leaves each
+# stage's IR in `<exe>.modules/`, which is where the equalities read it, and
+# means the chain exercises the same driver a user does.
+say "stage1: self/ compiled by $seed_label"
+rm -rf "$work/stage1.modules"
+# This is the step the rolling freeze is enforced by, so it says so when it
+# fails rather than leaving a reader with the compiler's own diagnostic and no
+# idea which rule it just met.
+if ! run_seed self/compile.ts --link "$work/stage1" --profile "$profile" >/dev/null; then
+  echo "bootstrap: $seed_label could not build stage1 from self/ (its output is above)" >&2
+  echo "bootstrap: if it refused the source, that is the freeze doing its job: a construct" >&2
+  echo "bootstrap: added in 0.N cannot be used by self/ until 0.(N+1) (docs/wp12-release.md," >&2
+  echo "bootstrap: \"The bootstrap seed\"; docs/wp19-stage0-retirement.md §3, G3)" >&2
+  exit 1
+fi
+
+if [ "$build_to" -ge 2 ]; then
+  say "stage2: self/ compiled by stage1"
+  link_stage "$work/stage1" stage2
+  # The seed equality, reported and not asserted.
+  [ "$verify" -eq 1 ] && survey_ir "$work/stage1.modules" "$work/stage2.modules"
+fi
+
+if [ "$build_to" -ge 3 ]; then
+  say "stage3: self/ compiled by stage2"
+  link_stage "$work/stage2" stage3
+  [ "$verify" -eq 1 ] && compare_ir "$work/stage2.modules" "$work/stage3.modules" "IR(stage1) == IR(stage2)"
+  # `stage3 == stage2`, in scripts/verify-binaries.sh: byte-identical, which
+  # both stages being linked at one path is what buys on Mach-O as well. Under
+  # that, on Darwin, it still asserts the size, strips debug information where
+  # a tool can strip it, and fails anything left over as *unattributed* -- a
+  # net now rather than the arm that decides a darwin row. The comparison lives
+  # in a script of its own so that tests/run.js can drive every branch of it
+  # from one machine -- its header is where the reasoning is, and NISH_UNAME_S
+  # is how the suite asks for the other platform's branch.
+  if [ "$verify" -eq 1 ]; then
+    if verdict="$(bash scripts/verify-binaries.sh "$work/stage2" "$work/stage3" 2>&1)"; then
+      printf '%s\n' "$verdict" | while IFS= read -r line; do say "  $line"; done
+    else
+      printf '%s\n' "$verdict" >&2
+      exit 1
+    fi
+  fi
+fi
+
+cp "$work/stage$install" "$out"
+say "bootstrap: wrote $out ($(wc -c < "$out" | tr -d ' ') bytes, stage$install, $profile profile)"
+say "           it takes -o <file.ll>, -o <dir>/, --link <exe> and --profile"

package/scripts/build.sh

@@ -0,0 +1,279 @@
+#!/usr/bin/env bash
+# Build an Nish .ll module (plus optional C sources) into a native binary.
+#
+#   scripts/build.sh <module.ll> [more .ll/.c files...] -o <out> [--profile debug|speed|size|wasm]
+#
+# The C runtime is three translation units and is named as one: an input
+# <dir>/runtime.c also compiles <dir>/runtime_os.c, the half that wraps the
+# system calls (files, directories, subprocesses, the environment, the clock),
+# and <dir>/runtime_parallel.c, the half that divides a range of work across
+# threads. Each of those files says why they are compiled and measured apart.
+#
+# Profiles:
+#   debug  clang defaults: no optimisation, symbols kept. The "before" number.
+#   speed  -O3 + LTO + section GC + strip. Rust `--release` equivalent.
+#   size   -Oz + LTO + section GC + strip + no unwind tables. Rust
+#          `opt-level="z"`, `panic="abort"`, `strip=true` equivalent.
+#   wasm   wasm32 freestanding module exporting every non-internal function;
+#          load it from Node. Add runtime/runtime_wasm.c to the inputs when a
+#          function uses arrays (the arena and the array cold paths, no libc);
+#          strings and I/O still need a WASI runtime and are not available.
+#   wasm   wasm32 freestanding module exporting every non-internal function
+#          (for modules that do not use the C runtime); load it from Node.
+#   wasi   wasm32-wasi command module: runtime.c linked against wasi-libc, so
+#          string programs run under any WASI host (`_start` runs `main`;
+#          `node examples/wasi-host.mjs app.wasm args...`). Needs a WASI
+#          sysroot: WASI_SYSROOT=<dir>, or /usr/lib/wasi-sysroot,
+#          /opt/wasi-sdk/share/wasi-sysroot, /usr/share/wasi-sysroot.
+#   napi   Node addon (<out>.node): the speed flags plus -shared -fPIC, built
+#          against the Node headers next to `node` (override: NODE_INCLUDE=<dir
+#          containing node_api.h>). Inputs: <modules.ll> runtime/runtime.c and
+#          the shim from `nish --emit-napi`.
+#
+# Profile-guided optimisation (WP9), for the speed, size and napi profiles:
+#   --pgo-generate         instrumented build (-fprofile-generate); running the
+#                          binary writes default_*.profraw into the current
+#                          directory (or $LLVM_PROFILE_FILE)
+#   --pgo-use <profdata>   optimise with a merged profile (-fprofile-use=<file>)
+# Recipe:
+#   scripts/build.sh app.ll runtime/runtime.c -o app.instr --profile speed --pgo-generate
+#   ./app.instr <typical input>            # one or more training runs
+#   llvm-profdata merge -o app.profdata default_*.profraw
+#   scripts/build.sh app.ll runtime/runtime.c -o app --profile speed --pgo-use app.profdata
+# The instrumented link needs the compiler-rt profile runtime (Ubuntu:
+# libclang-rt-<ver>-dev; it ships with Apple clang and Homebrew llvm).
+# docs/wp9-optimisation.md reports what PGO buys on the benchmark suite.
+#
+# Threads (WP20 T0): `--threads` compiles every input with -DNISH_THREADS, which
+# makes the arena and the RNG seed in runtime/runtime.c thread-local. Pass it
+# exactly when the IR was compiled with `nish --threads` (`nish --threads
+# --link` does it for you): compiled modules reference `@nish_arena` as a
+# thread-local global, and ELF will not link that against a non-TLS definition,
+# so a half-threaded build fails at the link rather than at run time.
+#
+# Debug info (WP10): `-g` compiles every input with -g and skips the strip
+# step of the speed/size/napi profiles, so the DWARF that `nish -g`
+# put in the .ll (line table, variables) reaches the binary. `nish
+# --link -g` passes it through automatically.
+#
+# Works on Linux (clang + lld preferred, GNU ld tolerated) and macOS (Apple ld64
+# or Homebrew llvm). Set CC to pick a compiler (default: clang on PATH).
+set -euo pipefail
+
+profile=speed
+out=""
+inputs=()
+pgo=()                                 # -fprofile-generate / -fprofile-use=<file>
+debug=0                                # -g: keep DWARF (nish -g emits it in the IR; runtime.c gets it here)
+threads=0                              # --threads: -DNISH_THREADS, the thread-local arena (WP20 T0)
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -o) out="$2"; shift 2 ;;
+    --profile) profile="$2"; shift 2 ;;
+    -g) debug=1; shift ;;
+    --threads) threads=1; shift ;;
+    --pgo-generate) pgo=(-fprofile-generate); shift ;;
+    --pgo-use)
+      [ -f "$2" ] || { echo "error: --pgo-use: profile '$2' not found (run the instrumented binary, then llvm-profdata merge)" >&2; exit 2; }
+      pgo=("-fprofile-use=$2"); shift 2 ;;
+    -h|--help) sed -n '2,41p' "$0"; exit 0 ;;
+    *) inputs+=("$1"); shift ;;
+  esac
+done
+[ ${#inputs[@]} -gt 0 ] || { echo "error: no input files" >&2; exit 2; }
+[ -n "$out" ] || { echo "error: -o <out> is required" >&2; exit 2; }
+
+# The runtime is three translation units, and a caller names one: whoever passes
+# <dir>/runtime.c gets <dir>/runtime_os.c and <dir>/runtime_parallel.c compiled
+# beside it. They were one file until the operating-system half was split out
+# for its own size budget, and the parallel half followed for the same reason
+# (each file's header comment says why), and a link line is where those splits
+# would otherwise leak: `nish --link` builds its command line in
+# self/compile.ts, the published package's recipe in every document and
+# README names runtime.c, and a user's own clang line does too. Pairing them
+# here keeps every one of those correct, and keeps "the runtime" one thing to
+# name from the outside. A caller that names one itself is left alone, because
+# naming one object twice is a duplicate-symbol error.
+for i in ${inputs[@]+"${inputs[@]}"}; do
+  case "$i" in
+    */runtime.c|runtime.c)
+      for half in runtime_os.c runtime_parallel.c; do
+        side="${i%runtime.c}$half"
+        have=0
+        for j in "${inputs[@]}"; do
+          if [ "$j" = "$side" ]; then have=1; fi
+        done
+        if [ "$have" = 0 ] && [ -f "$side" ]; then inputs+=("$side"); fi
+      done ;;
+  esac
+done
+
+CC=${CC:-clang}
+common=(-Wno-override-module)          # our IR is target-neutral; clang fills the triple in
+elf=()                                 # flags that only make sense for ELF targets
+
+# Platform-specific dead-stripping, symbol stripping and LTO linker selection.
+case "$(uname -s)" in
+  Darwin)
+    # ld64: -dead_strip is the --gc-sections equivalent, -x drops local symbols
+    # (-s is deprecated on macOS). No -fuse-ld=lld: ld64 does LTO natively.
+    #
+    # NOT -no_uuid, however tempting it looks from the reproducibility side.
+    # LC_UUID is what made two links of one input differ here -- measured, on
+    # both darwin rows (docs/wp10-ci.md#ci-matrix) -- and dropping it does make
+    # them identical, and the binary then does not run: on arm64 dyld refuses
+    # an image with no LC_UUID outright, `missing LC_UUID load command`
+    # followed by SIGABRT, so the stage1 that linked went on to abort the
+    # moment the bootstrap ran it. Measured too, on the run after the one that
+    # named the UUID. An unloadable compiler is worse than any reproducibility,
+    # so the UUID stays. The ELF branch's --build-id=none below is the flag
+    # this would have been; ELF has no loader that insists on one.
+    #
+    # It costs nothing, because the UUID was measured stable across two links
+    # of one input to one output path, and differing on a link to another. That
+    # is what scripts/bootstrap.sh links every comparable stage at one path for,
+    # and it is why `stage3 == stage2` holds on Mach-O with the load command in.
+    gc=(-Wl,-dead_strip); strip_flag=(-Wl,-x) ;;
+  *)
+    gc=(-Wl,--gc-sections -Wl,--as-needed -Wl,-O2 -Wl,--build-id=none); strip_flag=(-s)
+    elf=(-fno-plt)
+    # GNU ld needs the gold plugin for LTO; prefer lld when clang can find it.
+    if command -v ld.lld >/dev/null 2>&1; then common+=(-fuse-ld=lld); fi ;;
+esac
+
+# -g: compile everything with debug info and never strip, whatever the profile,
+# so the line table nish emitted survives into the binary.
+if [ "$debug" = 1 ]; then common+=(-g); strip_flag=(); fi
+
+# --threads: the storage class of the arena is ABI, so every input is compiled
+# with the same macro -- C runtime and generated N-API shim alike.
+#
+# -ftls-model=initial-exec names, for the C side, the model the IR already
+# names. Without it a -fPIC build (the napi profile) reaches the arena through
+# a __tls_get_addr call, so the two halves of one inlined allocator would use
+# two different models; it is also smaller (4,759 bytes of runtime.c `.text*`
+# against 4,820 at -Oz -fPIC) and free where the model was local-exec anyway.
+#
+# `tls` is the same pair again for the wasm and wasi profiles, which build their
+# own command line instead of using `common`; it is empty on every ordinary
+# build, hence the bash 3.2 expansion spelling explained below.
+#
+# -pthread is for runtime_parallel.c, the translation unit that divides a range
+# of work across threads: it is compiled in either configuration and only spawns
+# under this macro, so this is the build where the flag has to be on the command
+# line. On a current glibc the library half is already inside libc and the link
+# would succeed without it; passing it is what makes that an implementation
+# detail rather than something the build depends on.
+#
+# It is deliberately in `common` and not in `tls`: `tls` is the wasm and wasi
+# command lines, which have no threads to link against, and where
+# runtime_parallel.c compiles to its sequential fallback because it tests
+# __wasi__ and __wasm__ as well as the macro.
+tls=()
+if [ "$threads" = 1 ]; then
+  common+=(-DNISH_THREADS=1 -ftls-model=initial-exec -pthread)
+  tls=(-DNISH_THREADS=1 -ftls-model=initial-exec)
+fi
+
+# The ${arr[@]+"${arr[@]}"} spelling below is not a style tic: macOS ships bash
+# 3.2 (Apple will not ship GPLv3), where expanding an empty array as "${arr[@]}"
+# under `set -u` is a fatal "unbound variable" -- bash 4.4 made it legal, which is
+# why Linux never noticed. `pgo`, `elf`, `strip_flag` and `libs` are all empty on
+# ordinary builds, so please do not simplify these back.
+case "$profile" in
+  debug)
+    "$CC" "${common[@]}" "${inputs[@]}" -lm -o "$out" ;;
+  speed)
+    "$CC" "${common[@]}" -O3 -flto -DNDEBUG ${pgo[@]+"${pgo[@]}"} \
+      -ffunction-sections -fdata-sections -fomit-frame-pointer \
+      -fno-asynchronous-unwind-tables -fno-unwind-tables ${elf[@]+"${elf[@]}"} \
+      "${gc[@]}" ${strip_flag[@]+"${strip_flag[@]}"} "${inputs[@]}" -lm -o "$out" ;;
+  size)
+    "$CC" "${common[@]}" -Oz -flto -DNDEBUG ${pgo[@]+"${pgo[@]}"} \
+      -ffunction-sections -fdata-sections -fomit-frame-pointer \
+      -fno-asynchronous-unwind-tables -fno-unwind-tables ${elf[@]+"${elf[@]}"} \
+      -fno-stack-protector -fvisibility=hidden \
+      "${gc[@]}" ${strip_flag[@]+"${strip_flag[@]}"} "${inputs[@]}" -lm -o "$out" ;;
+  wasm)
+    # clang resolves wasm-ld next to its own binary first, then on PATH; ask it
+    # rather than probing PATH so a Homebrew llvm without a PATH entry still works.
+    wasm_ld=$("$CC" -print-prog-name=wasm-ld)
+    if [ ! -x "$wasm_ld" ]; then
+      echo "error: the wasm profile needs wasm-ld (install lld; on macOS: brew install llvm@18)" >&2
+      exit 2
+    fi
+    # -mbulk-memory lowers llvm.memset/memcpy (`new Array<T>(n)`, `push` growth) to the
+    # memory.fill/memory.copy instructions instead of libc calls the freestanding link lacks.
+    "$CC" -Wno-override-module --target=wasm32-unknown-unknown -Oz -nostdlib -mbulk-memory \
+      ${tls[@]+"${tls[@]}"} \
+      -Wl,--no-entry -Wl,--export-all -Wl,--strip-all -Wl,--gc-sections \
+      "${inputs[@]}" -o "$out" ;;
+  wasi)
+    sysroot=${WASI_SYSROOT:-}
+    for d in /usr/lib/wasi-sysroot /opt/wasi-sdk/share/wasi-sysroot /usr/share/wasi-sysroot; do
+      [ -n "$sysroot" ] || { [ -d "$d" ] && sysroot=$d; }
+    done
+    if [ -z "$sysroot" ] || [ ! -d "$sysroot/lib" ]; then
+      echo "error: the wasi profile needs a WASI sysroot (wasi-libc headers and libc.a) and none was found." >&2
+      echo "       Install wasi-sdk's sysroot (https://github.com/WebAssembly/wasi-sdk/releases: wasi-sysroot-<ver>.tar.gz," >&2
+      echo "       or apt install wasi-libc) and set WASI_SYSROOT=<dir> if it is not in one of the default locations" >&2
+      echo "       (/usr/lib/wasi-sysroot, /opt/wasi-sdk/share/wasi-sysroot, /usr/share/wasi-sysroot). See docs/INSTALL.md." >&2
+      exit 2
+    fi
+    wasm_ld=$("$CC" -print-prog-name=wasm-ld)
+    if [ ! -x "$wasm_ld" ]; then
+      echo "error: the wasi profile needs wasm-ld (install lld; on macOS: brew install llvm@18)" >&2
+      exit 2
+    fi
+    # clang links compiler-rt's wasm32 builtins from its resource dir (wasi-sdk and Debian's
+    # libclang-rt-<ver>-dev-wasm32 put it there); wasi-libc's strtoll needs its __multi3.
+    # Otherwise look for wasi-sdk's separate libclang_rt.builtins-wasm32-wasi-<ver>.tar.gz
+    # unpacked next to the sysroot, or WASI_BUILTINS=<file>, and name libc explicitly
+    # (wasi-libc's libc.a includes libm) so clang stops looking for the archive itself.
+    libs=()
+    if [ ! -f "$("$CC" -print-resource-dir)/lib/wasi/libclang_rt.builtins-wasm32.a" ]; then
+      for f in "${WASI_BUILTINS:-}" "$sysroot/lib/wasm32-wasi/libclang_rt.builtins-wasm32.a" \
+               "$sysroot/lib/libclang_rt.builtins-wasm32.a" "$sysroot"/../libclang_rt.builtins-wasm32*/libclang_rt.builtins-wasm32.a; do
+        if [ -n "$f" ] && [ -f "$f" ]; then libs=(-nodefaultlibs -lc "$f"); break; fi
+      done
+      if [ ${#libs[@]} -eq 0 ]; then
+        echo "error: the wasi profile needs compiler-rt's wasm32 builtins (libclang_rt.builtins-wasm32.a) and clang has none." >&2
+        echo "       Install libclang-rt-<ver>-dev-wasm32, or unpack wasi-sdk's libclang_rt.builtins-wasm32-wasi-<ver>.tar.gz" >&2
+        echo "       into $sysroot/lib/wasm32-wasi/ or point WASI_BUILTINS at the .a file. See docs/INSTALL.md." >&2
+        exit 2
+      fi
+    fi
+    "$CC" -Wno-override-module --target=wasm32-wasi --sysroot="$sysroot" -Oz -DNDEBUG \
+      ${tls[@]+"${tls[@]}"} \
+      -ffunction-sections -fdata-sections -Wl,--gc-sections -Wl,--strip-all \
+      "${inputs[@]}" ${libs[@]+"${libs[@]}"} -o "$out" ;;
+  napi)
+    # Node ships its C headers next to the binary: <prefix>/bin/node and
+    # <prefix>/include/node/node_api.h (official tarballs, nvm, fnm, volta).
+    # Distro packages put them in libnode-dev; NODE_INCLUDE overrides the guess.
+    node_bin=${NODE:-node}
+    node_inc=${NODE_INCLUDE:-}
+    if [ -z "$node_inc" ]; then
+      node_inc=$("$node_bin" -p "require('path').dirname(process.execPath) + '/../include/node'" 2>/dev/null || true)
+    fi
+    if [ -z "$node_inc" ] || [ ! -f "$node_inc/node_api.h" ]; then
+      echo "error: the napi profile needs the Node headers, but ${node_inc:-<node not found>}/node_api.h does not exist." >&2
+      echo "       Install Node from nodejs.org/nvm (they ship include/node), or apt install libnode-dev and" >&2
+      echo "       set NODE_INCLUDE=/usr/include/node (any directory that contains node_api.h)." >&2
+      exit 2
+    fi
+    shared=(-shared -fPIC)
+    # macOS: the napi_* symbols come from the node binary at load time, so the
+    # linker must not insist on resolving them. ELF shared objects allow this.
+    case "$(uname -s)" in Darwin) shared+=(-Wl,-undefined,dynamic_lookup) ;; esac
+    # runtime/nish.h is the public ABI header the generated shim includes.
+    runtime_inc="$(cd "$(dirname "$0")/../runtime" && pwd)"
+    "$CC" "${common[@]}" -O3 -flto -DNDEBUG ${pgo[@]+"${pgo[@]}"} -I"$node_inc" -I"$runtime_inc" \
+      -ffunction-sections -fdata-sections -fomit-frame-pointer \
+      -fno-asynchronous-unwind-tables -fno-unwind-tables ${elf[@]+"${elf[@]}"} \
+      "${shared[@]}" "${gc[@]}" ${strip_flag[@]+"${strip_flag[@]}"} "${inputs[@]}" -lm -o "$out" ;;
+  *) echo "error: unknown profile '$profile'" >&2; exit 2 ;;
+esac
+
+# `wc -c` pads with spaces on macOS; strip them so the number is clean.
+printf '%s: %s bytes (%s)\n' "$out" "$(wc -c < "$out" | tr -d ' ')" "$profile"