pkg cross-compile test harness

Validates pkg cross-OS and cross-arch support across Node 20/22/24 and Standard vs Enhanced SEA modes. Produces a consistent result table so claims in docs and issues can be checked against reality.

When to use

• User is about to edit docs about cross-compile support and needs ground truth.
• User is looking at a cross-compile issue (e.g. #87, #181) and wants to reproduce it.
• User bumped pkg-fetch or touched bootstrap/prelude and wants a smoke test across targets.
• User wants to know whether a regression is Node-version specific.

Host requirements

This harness is designed for a Linux x86_64 host with:

• nvm with node 20, 22, and 24 installed (nvm install 20 22 24).
• docker daemon running.
• docker image scottyhardy/docker-wine (pulled on first win-x64 run).
• tonistiigi/binfmt installed for cross-arch containers — if you see exec format error on arm64 runs, install with:

  docker run --privileged --rm tonistiigi/binfmt --install arm64

• pkg built from this repo (yarn build) so lib-es5/bin.js exists. The script resolves the pkg entry from its own location — it lives at .claude/skills/pkg-xcompile-test/run-matrix.sh and defaults PKG_BIN to <repo-root>/lib-es5/bin.js.

Not supported: macOS runtime verification. docker-osx needs /dev/kvm and darling is dead. macOS regressions have to be caught on a real Mac or on the GitHub Actions macos-* runners — note that in the final report.

What it runs

For each Node major (20, 22, 24) the harness:

1. Uses nvm use $major so the pkg host node matches the target node major. This matters — SEA's blob generator uses host execPath when host-major == target-major, otherwise tries to run the downloaded target-arch node binary (which fails without cross-arch emulation).
2. Loops over modes × targets:
   • Modes: std, std-public (--public-packages "*" --public), sea
   • Targets: linux-x64, linux-arm64, win-x64, macos-x64, macos-arm64
3. Records build result (OK / FAIL), then tries to run the binary:
   • linux-x64 → native
   • linux-arm64 → docker run --platform linux/arm64 ubuntu:latest
   • win-x64 → docker run scottyhardy/docker-wine (see gotcha below)
   • macos-* → skipped (SKIP-no-mac)
4. Prints a summary table.

Wine gotcha

wine inside a non-tty docker container produces invalid stdio file descriptors, causing Node to crash with Error: open EBADF before any user code runs. The workaround is to redirect wine's stdout/stderr to files inside the container, then cat them back:

docker run --rm -v "$BINDIR:/mnt" scottyhardy/docker-wine \
  bash -c "wine '/mnt/app.exe' </dev/null >/tmp/out 2>/tmp/err; cat /tmp/out"

Without this, every wine run will look like a pkg failure when it isn't.

Usage

Run from the repo root (paths in the examples are relative to it).

Quick run (single node version)

# Runs the full matrix for node 22 targets with node 22 as host
./.claude/skills/pkg-xcompile-test/run-matrix.sh 22

Full sweep (20 + 22 + 24)

for V in 20 22 24; do
  ./.claude/skills/pkg-xcompile-test/run-matrix.sh $V
done

Custom pkg build

./.claude/skills/pkg-xcompile-test/run-matrix.sh 22 /path/to/other/pkg/lib-es5/bin.js

Custom work directory

By default build outputs go to /tmp/pkg-xcompile/bin-node<major>/. Override with:

PKG_XCOMPILE_WORKDIR=/somewhere/else ./.claude/skills/pkg-xcompile-test/run-matrix.sh 22

Reading the output

Each cell is BUILD / RUN:

• OK / OK — works
• OK / FAIL — built, but runtime error on target
• FAIL / n/a — build failed
• OK / SKIP-no-mac — can't test macOS runtime on this host

Known results (captured 2026-04-15)

Host: Ubuntu 24.04 x86_64, pkg HEAD of docs/github-pages-site. Tests run with matching host-node / target-node major.

Node 20

Standard cross-compile on Node 20 works without workarounds. SEA mode is unavailable because pkg enforces host node ≥ 22.

Node 22

Standard cross-compile on Node 22 is broken:

• linux-arm64 crashes at runtime with Error: UNEXPECTED-20 in readFileFromSnapshot. Matches the #181 failure mode.
• win-x64 exits silently with EXIT=4 and no stdout. Matches the #87 Windows silent-exit bug.

Both are fixed by adding --public-packages "*" --public (which skips the V8 bytecode step). Enhanced SEA avoids both out of the box.

Node 24

Node 24 works out of the box for Standard and SEA, same as Node 20. The Node 22 bug is a Node-22-specific pkg-fetch patch regression, not a permanent Standard-mode limitation.

macOS runtime

Not verified — see "Host requirements" above. The regressions tracked in #181 (macOS host, Node 22+) must be confirmed on a real Mac. GitHub Actions' macos-13 / macos-14 runners are the right place for that; a follow-up CI workflow that runs the hello.js matrix there would close the last hole.

Debugging a failing run

Each cell writes its own log; paths are printed on stderr next to any FAIL and re-summarised at the end of the run.

• Log location — $PKG_XCOMPILE_WORKDIR/logs/node<major>/build-<mode>-<target>.log (and run-<mode>-<target>.log). Default workdir is /tmp/pkg-xcompile. Logs are per-cell so a failing build is not overwritten by the next one.
• Re-run one cell — the fastest way is still to invoke pkg directly against the same fixture:

  cd /tmp/pkg-xcompile
  node /path/to/pkg/lib-es5/bin.js hello.js -t node22-linux-arm64 \
    -o /tmp/pkg-xcompile/bin-node22/std-linux-arm64

• exec format error on arm64 runs — binfmt is not registered. After a reboot tonistiigi/binfmt needs to be re-installed:

  docker run --privileged --rm tonistiigi/binfmt --install arm64

• Wine cell always FAIL — pull the image manually once (docker pull scottyhardy/docker-wine) and inspect logs/node<major>/run-sea-win-x64.log for the actual crash. The EBADF-stdout gotcha is documented above.
• SEA FAIL on Node 20 — expected; pkg enforces host node ≥ 22 for SEA.
• Error: UNEXPECTED-20 / silent exit (EXIT=4) — these are the tracked Node-22 Standard-mode regressions (issues #181 and #87). Not environment bugs — see Node 22 results below.
• Stale binary hiding a regression — pkg does not hash its own source into the output. After rebuilding pkg, delete bin-node<major>/ before re-running the matrix.

The script

The harness lives next to this SKILL.md as run-matrix.sh. Before first run, set PKG_BIN to your pkg build and ensure nvm is sourced.

Quick reference of pkg flags touched

Notes for future maintainers

• Do not reuse cached binaries between matrix runs — delete bin-node${major}/ first if you rebuilt pkg. pkg does not hash its own source into the output, so stale binaries silently hide regressions.
• If you add a new target to the matrix, also add a runner branch in run_one(). Unknown targets fall through the case and count as pass.
• If scottyhardy/docker-wine becomes unavailable, tobix/wine is a smaller drop-in replacement — it has the same EBADF stdout gotcha.
• Don't confuse "builds with warning" with "builds clean". The matrix only records OK when the binary file exists on disk; a warning like Failed to make bytecode node22-arm64 still produces a binary but it will crash at runtime. Runtime is the source of truth.