@amritk/nish 0.10.0

package/scripts/postinstall.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Put the native compiler on PATH directly, when this machine got one.
+ *
+ * `bin/nish` ships as a node shim that resolves the prebuilt binary and spawns
+ * it. That works everywhere and costs node's startup on every invocation --
+ * 94 ms against the binary's own 2.7 ms, which is nothing for a single build
+ * and is 80 seconds across a suite that spawns a compiler per case. So when a
+ * `@amritk/nish-<asset>` package did get installed, this replaces the shim
+ * with a one-line `exec` of that package's binary: 3.9 ms, and no node.
+ *
+ * **It execs the binary where it lies; it does not copy it here.** Copying was
+ * the first attempt and it is wrong, for a reason worth writing down because
+ * nothing in the test suite was looking for it. npm links the command as
+ * `node_modules/.bin/nish -> ../@amritk/nish/bin/nish`, so a user always
+ * invokes it through a symlink, and the native compiler resolves `build.sh`
+ * and `runtime/` from `argv[0]`'s directory without following one. A copy at
+ * `@amritk/nish/bin/nish` invoked through `.bin` therefore looks for them in
+ * `node_modules/`, finds neither, and every `--link` fails with "cannot find
+ * scripts/build.sh" -- while `--version` and plain `-o` keep working, which is
+ * what makes it a trap. The node shim never had the problem because node
+ * resolves `import.meta.url` to the realpath.
+ *
+ * Execing an absolute path sidesteps it entirely and is better on its own
+ * terms: the binary runs from inside its own package, next to the `runtime/`
+ * and `scripts/` that were staged and smoke-tested beside it by `release.yml`,
+ * rather than beside the main package's copies.
+ *
+ * **The compiler resolves the link itself as of 0.6.0** -- the real path of
+ * whatever `argv[0]` named is a candidate for the package root
+ * ([wp19 §5a](../docs/wp19-stage0-retirement.md) item 4, in `self/`) -- so this
+ * `exec` is no longer what makes a copy work, and the reason it is still here is
+ * the 91 ms above rather than the defect. It also still carries whoever never
+ * ran this script: a shim npm linked and nothing swapped now finds its own
+ * package too.
+ *
+ * **This script may never fail an install.** It exits 0 whatever happens --
+ * no prebuilt binary for this platform, a read-only `node_modules`, scripts
+ * disabled, a partially written package. Every one of those leaves the shim in
+ * place, and the shim is the mechanism this only optimises: where a prebuilt
+ * binary exists it finds it, and where none does it says so and exits 3. What
+ * it is *not*, since 0.6.0, is a compiler of its own -- `dist/` is no longer in
+ * the package -- so "the shim is still there" means the command still behaves
+ * correctly, not that it can still compile on a platform with no binary. A
+ * postinstall that can break `npm ci` is a worse bug than the startup cost it
+ * exists to remove.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+
+const root = path.resolve(import.meta.dirname, "..");
+
+const swap = async () => {
+  // A checkout, not an install. The repository is its own package, so `npm ci`
+  // here installs this package's own optionalDependencies -- and without this
+  // guard, the first `npm ci` after they are published would overwrite the
+  // tracked `bin/nish` with a binary and leave the working tree dirty. The
+  // landmark is `self/compile.ts`, which is the check `scripts/bootstrap.sh`
+  // makes and is not in `files`; it used to be `src/launcher.ts`, which stopped
+  // being a landmark when the launcher moved into `bin/` and ships.
+  if (fs.existsSync(path.join(root, "self", "compile.ts"))) return "a checkout, so the shim stays";
+
+  const shim = path.join(root, "bin", "nish");
+  if (!fs.existsSync(shim)) return "no bin/nish to replace";
+
+  const packaging = path.join(root, "bin", "packaging.js");
+  if (!fs.existsSync(packaging)) return "bin/packaging.js is missing";
+  const { assetFor, platformPackageName } = await import(pathToFileURL(packaging).href);
+  const asset = assetFor(process.platform, process.arch);
+  if (asset === null) return `no prebuilt binary for ${process.platform}/${process.arch}`;
+
+  const name = platformPackageName(
+    JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).name,
+    asset
+  );
+  let binary;
+  try {
+    const manifest = createRequire(import.meta.url).resolve(`${name}/package.json`);
+    binary = path.join(path.dirname(manifest), "bin", "nish");
+  } catch {
+    return `${name} is not installed`;
+  }
+  if (!fs.existsSync(binary)) return `${name} carries no bin/nish`;
+
+  // The absolute path is baked in at install time, which is the one thing this
+  // gives up: a `node_modules` copied to a different path without a reinstall
+  // leaves a shim pointing at nothing. The `-x` test is what turns that from a
+  // confusing exec failure into a sentence naming the fix, and `npm rebuild`
+  // re-runs this script and rewrites the path.
+  //
+  // Written beside the target and renamed, so a process running `nish` while
+  // this runs never sees a half-written one; rename is atomic within a
+  // directory, and the temporary file is cleaned up if it is not.
+  //
+  // Single quotes, not `JSON.stringify`. JSON escaping is not shell escaping:
+  // it leaves `$` and a backtick alone, and inside the double quotes they would
+  // have ended up in, the shell would expand them. A home directory with a `$`
+  // in it is unusual and entirely legal. In POSIX sh nothing is special inside
+  // single quotes, so the only thing to handle is a single quote itself.
+  const shellQuote = (value) => `'${value.split("'").join(`'\\''`)}'`;
+  const target = shellQuote(binary);
+  const script =
+    "#!/bin/sh\n" +
+    "# Written by scripts/postinstall.mjs. `npm rebuild` regenerates it.\n" +
+    `if [ -x ${target} ]; then exec ${target} "$@"; fi\n` +
+    // Exit 3 is this project's toolchain code: the compiler could not be run,
+    // which is exactly what has happened (docs/wp12-release.md, "Exit codes").
+    'echo "nish: the prebuilt compiler is not where it was installed; run \'npm rebuild\' to repoint this" >&2\n' +
+    "exit 3\n";
+  const temp = `${shim}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temp, script);
+    fs.chmodSync(temp, 0o755);
+    fs.renameSync(temp, shim);
+  } catch (err) {
+    try {
+      fs.rmSync(temp, { force: true });
+    } catch {
+      // Nothing to do about it, and it is not worth a second message.
+    }
+    throw err;
+  }
+  return `bin/nish now execs the native compiler in ${name}`;
+};
+
+try {
+  console.log(`nish: ${await swap()}`);
+} catch (err) {
+  // Deliberately not an error: the shim is still there and still works.
+  console.log(`nish: keeping the node launcher (${err instanceof Error ? err.message : String(err)})`);
+}

package/scripts/size-report.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# Before/after binary size report for an Nish module + driver + runtime.
+#   scripts/size-report.sh [--markdown] [module.ll] [driver.c]
+#
+# Prints the runtime.c budget row (its -Oz text size) and one row per build
+# profile (debug, speed, size, and wasm when wasm-ld is available). --markdown
+# emits a GitHub-flavoured table, used by CI for the job summary; the default
+# is a plain aligned table. Linux and macOS.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+format=plain
+args=()
+for a in "$@"; do
+  case "$a" in
+    --markdown|--md) format=markdown ;;
+    -h|--help) sed -n '2,8p' "$0"; exit 0 ;;
+    *) args+=("$a") ;;
+  esac
+done
+ll=${args[0]:-build/add.ll}
+driver=${args[1]:-examples/main.c}
+mkdir -p build/size
+
+bytes() { wc -c < "$1" | tr -d ' '; }   # macOS wc pads with spaces
+row() {                                  # row <profile> <bytes> <command>
+  if [ "$format" = markdown ]; then
+    printf '| `%s` | %s | `%s` |\n' "$1" "$2" "$3"
+  else
+    printf '%-10s %10s  %s\n' "$1" "$2" "$3"
+  fi
+}
+
+if [ "$format" = markdown ]; then
+  printf '| Profile | Bytes | Command |\n| --- | ---: | --- |\n'
+else
+  printf '%-10s %10s  %s\n' PROFILE BYTES COMMAND
+fi
+# The runtime budgets (docs/wp7-runtime.md, "Runtime additions and budget"): each of the two
+# runtime translation units compiled alone at -Oz, the sum of its `.text*` sections, against
+# its own ceiling. The gate is `node tests/run.js budget`; this row is the same number for a
+# reader. It was reported here as the `text` *column* of `size` instead, which also counts
+# `.rodata` and the `.eh_frame` entries the size profile strips -- so this row read 4,696
+# against a 4,096 budget while the code it is about was at 2,775. Read-only data ships too, so
+# it gets its own row rather than being folded in: Ryu's two power-of-five tables are 9,888
+# bytes of it, and section GC keeps them out of any binary that never formats a double (WP15).
+# `.text.unlikely.` is summed with `.text` because a linked binary pays for both, and a ceiling
+# on `.text` alone can be met by moving code to another section instead of by shrinking it.
+text_sum() {                             # text_sum <object>: every .text* section, summed
+  size -A "$1" | awk '$1 ~ /^\.text/ { n += $2 } END { print n + 0 }'
+}
+sect() { size -A "$2" | awk -v s="$1" '$1 == s { print $2 }'; }
+"${CC:-clang}" -Oz -c runtime/runtime.c -o build/size/runtime.o
+"${CC:-clang}" -Oz -c runtime/runtime_os.c -o build/size/runtime_os.o
+row runtime "$(text_sum build/size/runtime.o)" \
+  "clang -Oz -c runtime/runtime.c && size -A (.text*; budget 3584)"
+row runtime_os "$(text_sum build/size/runtime_os.o)" \
+  "clang -Oz -c runtime/runtime_os.c && size -A (.text*; budget 1280)"
+row rodata "$(sect .rodata build/size/runtime.o)" "the core object's .rodata (no budget; the Ryu tables live here)"
+# `scripts/build.sh` compiles runtime_os.c beside any runtime.c it is handed, so naming the
+# core here builds the whole runtime -- and `--gc-sections` then drops whatever this module
+# never calls, which for `examples/add.ts` is all of it.
+for p in debug speed size; do
+  scripts/build.sh "$ll" runtime/runtime.c "$driver" -o "build/size/app-$p" --profile "$p" >/dev/null
+  row "$p" "$(bytes "build/size/app-$p")" "scripts/build.sh $ll runtime/runtime.c $driver --profile $p"
+done
+# The wasm profile needs wasm-ld; ask clang where it would look (it checks its own
+# bin dir before PATH). Skip the row when the linker is not installed.
+if [ -x "$("${CC:-clang}" -print-prog-name=wasm-ld)" ]; then
+  scripts/build.sh "$ll" -o build/size/app.wasm --profile wasm >/dev/null
+  row wasm "$(bytes build/size/app.wasm)" "scripts/build.sh $ll --profile wasm"
+fi

package/scripts/smoke.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Smoke test: build every example program with `--link` in the `size` profile,
+# run it, and print a table of binary sizes.
+#
+#   scripts/smoke.sh [examples-dir]      (default: examples/)
+#   npm run smoke                        (after `npm run build`)
+#   NISH=<nish> scripts/smoke.sh         with that compiler instead
+#
+# NISH names the compiler, run as scripts/nish-compiler.sh says: a native
+# `nish` directly and a Node entry point under node. Unset, it is build/nish,
+# what `npm run build` leaves.
+#
+# A program is any examples/**/*.ts that declares `export const main`. It
+# is expected to exit 0 unless it carries a `// smoke: exit <n>` comment; a
+# `// smoke: argv <args>` comment passes those arguments on its command line
+# (process.argv). The script exits non-zero if any program fails to compile,
+# link, or run with the expected status. Binaries and IR go to build/smoke/.
+# Needs clang on PATH.
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+examples=${1:-examples}
+out=build/smoke
+mkdir -p "$out"
+
+# shellcheck source=scripts/nish-compiler.sh
+. scripts/nish-compiler.sh
+nish_compiler "${NISH:-build/nish}"
+
+if ! command -v clang >/dev/null 2>&1 && [ -z "${CC:-}" ]; then
+  echo "error: smoke test needs clang on PATH (see docs/INSTALL.md)" >&2
+  exit 3
+fi
+
+# Either spelling declares the entry (docs/wp22-arrow-functions.md): the arrow
+# `export const main = (...) => ...` is the form the corpus is written in, and
+# `export function main` is still legal.
+#
+# `mapfile` would say this in one line and is a bash 4 builtin: macOS ships
+# bash 3.2 (Apple will not ship GPLv3) and this script runs there too, since
+# WP19 G3 wants the matrix on both operating systems. `while read` over the
+# same pipeline is the portable spelling, and the process substitution keeps
+# the loop out of a subshell so `programs` survives it.
+programs=()
+while IFS= read -r program; do
+  programs+=("$program")
+done < <(grep -rl --include='*.ts' -E '^export (function main\b|const main[[:space:]]*=)' "$examples" | sort)
+if [ ${#programs[@]} -eq 0 ]; then
+  echo "error: no examples with \`export const main\` under $examples" >&2
+  exit 1
+fi
+
+failed=0
+rows=()
+for src in "${programs[@]}"; do
+  # examples/multi/main.ts -> multi_main; examples/hello.ts -> hello
+  name=$(printf '%s' "${src#"$examples"/}" | sed -e 's/\.ts$//' -e 's#/#_#g')
+  exe="$out/$name"
+  want=$(sed -n 's#^// smoke: exit \([0-9][0-9]*\).*#\1#p' "$src" | head -n 1)
+  want=${want:-0}
+  # `// smoke: args <flags>` passes extra compiler flags (e.g. --number-mode f64).
+  extra=$(sed -n 's#^// smoke: args \(.*\)#\1#p' "$src" | head -n 1)
+  # shellcheck disable=SC2086
+  if ! "${compiler[@]}" "$src" $extra --link "$exe" --profile size >"$out/$name.log" 2>&1; then
+    status="BUILD FAIL"
+    failed=1
+    sed 's/^/    /' "$out/$name.log" >&2
+    rows+=("$(printf '%-24s %10s  %s' "$src" "-" "$status")")
+    continue
+  fi
+  bytes=$(wc -c < "$exe" | tr -d ' ')   # macOS wc pads with spaces
+
+  # `// smoke: argv <args>` is the program's command line (WP7 process.argv).
+  argv=$(sed -n 's#^// smoke: argv \(.*\)#\1#p' "$src" | head -n 1)
+  # shellcheck disable=SC2086
+  "$exe" $argv >"$out/$name.out" 2>"$out/$name.err"
+  got=$?
+  if [ "$got" -eq "$want" ]; then
+    status="ok (exit $got)"
+  else
+    status="RUN FAIL (exit $got, expected $want)"
+    failed=1
+    sed 's/^/    /' "$out/$name.err" >&2
+  fi
+  rows+=("$(printf '%-24s %10s  %s' "$src" "$bytes" "$status")")
+done
+
+printf '%-24s %10s  %s\n' PROGRAM BYTES STATUS
+printf '%s\n' "${rows[@]}"
+if [ "$failed" -ne 0 ]; then
+  echo "smoke: FAILED" >&2
+  exit 1
+fi
+echo "smoke: ${#programs[@]} program(s) built (size profile) and ran"

package/scripts/verify-binaries.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# `stage3 == stage2`: the last of the equalities `scripts/bootstrap.sh --verify`
+# asserts, as a script of its own.
+#
+#   scripts/verify-binaries.sh <stage2> <stage3>
+#
+# Exit 0 and one or more lines on stdout saying what was compared; exit 1 and
+# the reason on stderr when the two binaries are not the same compiler.
+#
+# It is a file rather than a block inside bootstrap.sh for the reason
+# .github/seed-matrix.sh is one: it is a gate, it has arms that only one
+# operating system reaches, and a gate nothing can run is a gate nothing
+# checks. `tests/run.js` drives this script with fabricated files and
+# `NISH_UNAME_S` set, so every arm is reached from whatever machine the suite
+# runs on. Read the caveat under WHAT THE TESTS PROVE before trusting that
+# sentence further than it goes.
+#
+# THE COMPARISON. Two links of the same input produce the same bytes on ELF,
+# and that is the strongest form of "stage2 reproduces itself": it is asserted
+# there and nothing here relaxes it.
+#
+# On Mach-O they did not, and that was measured rather than expected: on
+# macos-latest (2026-09-13, WP19 R2) stage3 and stage2 differed at identical
+# size -- 597,048 bytes both -- while every IR equality in bootstrap.sh passed.
+# Same size, differing bytes: something small and fixed-width was not
+# reproducible, and it was the linker's rather than the compiler's.
+#
+# WHAT THAT SOMETHING WAS is now measured, and an earlier version of this
+# header first claimed it wrongly and then said, correctly, that nobody had run
+# it on a mac. Somebody has: a throwaway workflow ran release.yml's `binaries`
+# steps on both darwin rows on 2026-09-19 and attributed every differing byte
+# to the load command, section or linkedit blob it falls inside.
+#
+#   x86_64-darwin    649,808 bytes both, 16 differing, all at 0x468..0x478:
+#   (macos-15-intel) LC_UUID's sixteen bytes of UUID, and nothing else in the
+#                    file. `otool -l` diffed to the one `uuid` line.
+#
+#   aarch64-darwin   646,696 bytes both, 48 differing: the same sixteen at
+#   (macos-latest)   0x468, plus 33 in the LC_CODE_SIGNATURE blob at 0x9ca81 --
+#                    one SHA-256 code-directory slot. ld64 ad-hoc signs arm64
+#                    (`codesign -dvvv`: adhoc,linker-signed) and that slot is
+#                    the page hash of the page LC_UUID sits on, so the
+#                    signature is the consequence and the UUID the cause. The
+#                    Intel row, which ld64 does not sign at all, is the control
+#                    for that claim.
+#
+# So LC_UUID it was, as this header had guessed. The remedy it proposed was
+# wrong, and that is measured too: `-Wl,-no_uuid` does make the two files
+# identical, and dyld on arm64 then refuses to load either of them -- `missing
+# LC_UUID load command`, then SIGABRT -- so the stage links and will not start.
+# An unloadable compiler is worse than any reproducibility, and ELF's
+# `--build-id=none` has no Mach-O twin.
+#
+# WHAT SETTLED IT was one more measurement. Three links of one input by one
+# compiler, on both rows -- twice to the same output path, once to a different
+# one -- and what came back is that the UUID is STABLE ACROSS TWO LINKS TO ONE
+# PATH and DIFFERS ON A LINK TO ANOTHER, with nothing else in the file moving.
+# It is not a hash of the output's own content, then, which is what ld64
+# classic did and what would have made any two links of one input agree.
+#
+# The output path is the leading explanation and it is not the only one the
+# probe leaves standing. The two same-path links were invocations 1 and 2 and
+# the differing-path link was invocation 3, and the probe never went back to
+# the first path -- so path-identity and invocation-order are confounded, and
+# anything that had changed by the third link (a coarse clock tick, a
+# per-session counter, an intermediate name derived from the path rather than
+# equal to it) fits the same numbers. A fourth link back to the first path,
+# expected to reproduce the FIRST UUID, is the one line that would tell them
+# apart, and it was not run.
+#
+# The remedy holds either way, which is why this is left as it is rather than
+# guessed at: run 4 measured it end to end, with a real `bootstrap.sh --verify`
+# on both darwin rows, and got byte-identical stages. Whatever LC_UUID is a
+# function of, two stages linked at one path agree.
+#
+# That makes the failure the harness's rather than the toolchain's:
+# `scripts/bootstrap.sh` linked stage2 at `$work/stage2` and stage3 at
+# `$work/stage3`, so two compilers that agreed about every other byte were
+# guaranteed two different UUIDs. It links both at `$work/stage` now and moves
+# each into place afterwards, and both darwin rows reach the `cmp -s` above and
+# stop at it. Nothing below was relaxed to get there.
+#
+# The debug map, which an even earlier version of this header named, was never
+# it: bootstrap.sh defaults to `--profile speed` and never passes `-g`, so
+# there is no DWARF in the .o files for ld64 to build a map from, and build.sh
+# already dropped the local symbols at the link.
+#
+# WHAT IS ASSERTED ON DARWIN is therefore a net under a byte comparison that
+# now holds, rather than the arm that decides a darwin row. It costs nothing
+# while the two files are identical, and it is narrower than raw bytes and
+# wider than nothing when some future toolchain starts varying something else:
+#
+#   * the two files are the same SIZE. The measurement above is that they were,
+#     exactly, while differing -- so a difference in generated code, which is
+#     what this comparison exists to catch, has to keep the byte count to get
+#     past it. This is the assertion doing the work.
+#   * they are identical once debug information is stripped, where a tool on
+#     PATH can strip it. At `--profile speed` that is expected to remove
+#     nothing, per the debug-map paragraph above; it is kept because it costs
+#     nothing and because `--profile debug` does put DWARF in the .o files.
+#
+# A pair that is the same size and still differs after that is reported as
+# **unattributed** and fails. It fails because the alternative is a blanket
+# exemption that would accept a stage3 that is a different compiler, which is
+# the one thing this comparison is for; and it says "unattributed" rather than
+# "the code differs" because the one thing ld64 was measured to vary is already
+# accounted for by the shared link path, so what is left is unknown rather than
+# damning. The message carries the next step.
+#
+# WHAT THE TESTS PROVE. `tests/run.js` reaches every branch here, and for the
+# Darwin branches it does so two ways: with ELF pairs, which establish the
+# control flow only -- `NISH_UNAME_S=Darwin` changes which branch runs, not
+# what format the files are -- and with a fabricated minimal Mach-O pair
+# differing only in LC_UUID, which is the real format and the real field. That
+# second one is what says the unattributed arm is reachable with a benign pair,
+# and it is asserted as a known limitation rather than as a pass. It stays a
+# limitation of this script, and it has stopped describing what a bootstrap
+# produces: the stages still carry an LC_UUID each, and bootstrap.sh links them
+# at one path, so the two agree and there is no such pair to forgive.
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+  echo "usage: scripts/verify-binaries.sh <stage2> <stage3>" >&2
+  exit 2
+fi
+a="$1"
+b="$2"
+for f in "$a" "$b"; do
+  [ -f "$f" ] || { echo "verify-binaries: $f does not exist" >&2; exit 2; }
+done
+
+# Overridden by tests/run.js so both platforms' branches can be driven from one
+# machine. Announced when set, because a release build that had this in its
+# environment would assert a different equality and the log should say so.
+uname_s="$(uname -s)"
+if [ -n "${NISH_UNAME_S:-}" ] && [ "${NISH_UNAME_S}" != "$uname_s" ]; then
+  echo "verify-binaries: NISH_UNAME_S=$NISH_UNAME_S overrides the real platform ($uname_s); this is a test hook" >&2
+  uname_s="$NISH_UNAME_S"
+fi
+
+if cmp -s "$a" "$b"; then
+  echo "stage3 == stage2: byte-identical binaries"
+  exit 0
+fi
+
+if [ "$uname_s" != "Darwin" ]; then
+  echo "bootstrap: stage3 is not byte-identical to stage2" >&2
+  exit 1
+fi
+
+size_a=$(wc -c < "$a" | tr -d ' ')
+size_b=$(wc -c < "$b" | tr -d ' ')
+if [ "$size_a" != "$size_b" ]; then
+  {
+    echo "bootstrap: stage3 differs from stage2 and the two are not even the same size"
+    echo "bootstrap: ($size_a vs $size_b bytes). Whatever is not reproducible about ld64 is"
+    echo "bootstrap: small and fixed-width -- the size is not it. This is a difference in"
+    echo "bootstrap: what the compiler emitted (docs/wp10-ci.md#ci-matrix)."
+  } >&2
+  exit 1
+fi
+
+# A scratch directory of its own, so this never writes next to the binaries it
+# was handed -- bootstrap.sh's work directory is also where the next stage gets
+# built, and tests/run.js hands it files in a fixture it then compares.
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+stripped=0
+for tool in llvm-objcopy objcopy; do
+  if command -v "$tool" >/dev/null 2>&1 &&
+     "$tool" --strip-debug "$a" "$tmp/a" 2>/dev/null &&
+     "$tool" --strip-debug "$b" "$tmp/b" 2>/dev/null; then
+    stripped=1
+    break
+  fi
+done
+if [ "$stripped" -eq 0 ] && command -v strip >/dev/null 2>&1; then
+  cp "$a" "$tmp/a"
+  cp "$b" "$tmp/b"
+  if strip -x "$tmp/a" 2>/dev/null && strip -x "$tmp/b" 2>/dev/null; then
+    stripped=1
+  fi
+fi
+
+if [ "$stripped" -eq 1 ] && cmp -s "$tmp/a" "$tmp/b"; then
+  echo "stage3 == stage2: same size ($size_a bytes) and identical once debug information"
+  echo "was stripped; the raw bytes differ, which is ld64 and not the compiler"
+  exit 0
+fi
+
+{
+  echo "bootstrap: stage3 and stage2 are the same size ($size_a bytes) and still differ."
+  if [ "$stripped" -eq 1 ]; then
+    echo "bootstrap: Stripping debug information did not account for it -- which at"
+    echo "bootstrap: --profile speed is expected, because nothing put DWARF in the .o files"
+    echo "bootstrap: and build.sh already linked with -Wl,-x."
+  else
+    echo "bootstrap: No llvm-objcopy, objcopy or strip on PATH could strip either file, so"
+    echo "bootstrap: that half of the comparison did not run."
+  fi
+  echo "bootstrap:"
+  echo "bootstrap: This difference is UNATTRIBUTED. It is a failure rather than a warning,"
+  echo "bootstrap: because the alternative accepts a stage3 that is a different compiler."
+  echo "bootstrap: The one thing ld64 was measured to vary here is LC_UUID -- and on arm64"
+  echo "bootstrap: the code-directory slot that hashes the page it sits on. It was stable"
+  echo "bootstrap: across two links to one path, which is why scripts/bootstrap.sh links"
+  echo "bootstrap: every comparable stage at one path, and that was measured to hold end to"
+  echo "bootstrap: end. So either these two were not built that way, which \`otool -l\` will"
+  echo "bootstrap: show by disagreeing about the uuid, or ld64 is varying something new."
+  echo "bootstrap: Attribute the differing bytes before changing anything, the way the"
+  echo "bootstrap: first measurement was made (docs/wp10-ci.md#ci-matrix)."
+} >&2
+exit 1