Building & Running

On this page 5

Prerequisites

zig-js requires Zig 0.17.0-dev. The 0.16 release will not build it.

Important

If your system zig is 0.16, use a pinned 0.17-dev toolchain (e.g. installed under ~/.local/share/zig-0.17-dev/zig). The bun run docs:data script below auto-detects that path.

Important

zig-js resolves two sibling Zig packages by local path — ../zig-regex and ../zig-gc (see build.zig.zon). Both must be checked out next to your zig-js directory or the build cannot resolve its dependencies; CI provisions them from the zig-utils org.

The complete dependency-ownership policy is machine-checked. Run zig build dependency-audit after changing a package, system link, subprocess, script runtime, corpus, or acquisition input.

Build the library

zig build                 # builds libzig-js.a
zig build test            # unit tests (-Dtest-filter=<substr> narrows; -Dtsan=true for ThreadSanitizer)
zig build conformance     # fast local smoke suite (33/33; not a CI gate)
zig build bench           # bytecode VM vs tree-walk microbenchmarks
zig build benchmark-comparison # zig-js single/shared vs system JSC (macOS only)
zig build threads-test    # the multithreading (issue #1) suite — this is what CI gates

The engine comparison runs seven median-scored samples of eight shared workloads and validates their checksums across zig-js and the system JavaScriptCore. Use -Dbenchmark-comparison-quick=true for a reduced harness check, and see Performance Benchmarks for the method and latest saved result.

Run the real test262 suite

zig build test262 scores the pinned test262 git submodule by default, so initialize it first (a missing corpus is skipped cleanly, not an error):

git submodule update --init test262

# Runs the pinned tc39/test262 corpus with a crash-proof subprocess harness.
zig build test262 -Doptimize=ReleaseFast

# Point at an explicit corpus root:
zig build test262 -Dtest262=/path/to/test262 -Doptimize=ReleaseFast

The runner prints a per-subtree breakdown and a totals summary:

zig build test262 — summary

---------------------------------------------- VALID (can we run it): 48506/48506 (100%) parse-fail 0 · runtime-fail 0 · host-fail 0 NEGATIVE (strictness): 4669/4669 (100%) skipped (unsupported harness/path metadata): 0

Note

A cold ReleaseFast build can take ~25–30 minutes; a cached run of the suite is a couple of minutes. There is no wall-clock timeout — a step_budget bounds runtime instead.

Diagnostics

# Cluster failures within a single subtree
zig build diag -Doptimize=ReleaseFast -- run test/language

Updating the docs numbers

The conformance figures on this site live in docs/.data/test262.json. Regenerate them from a real run:

bun run docs:data                      # runs the suite and rewrites the JSON
bun run docs:data -- --from run.txt    # or parse a saved run's output

Every page that reads data.test262 (the homepage bar, the conformance page) updates automatically on the next bun run docs:build.

The docs commands run the owner-maintained BunPress checkout at ../../Tools/bunpress. bun run docs:build checks the complete rendered tree against docs/.data/bunpress-output-v1.json; use bun run docs:manifest only when you intend to accept and review a renderer or content-output change.

To inspect what is still outside the denominator:

zig build test262-bin
./zig-out/bin/test262 --list-skips > docs/.data/test262-skips.tsv
./zig-out/bin/test262 --list-excluded > docs/.data/test262-excluded.tsv