Building and Integration

Building and Integration

Who this is for: consumers integrating es-parser and anyone building the repo.

Requirements

Zig 0.17.0-dev.607+456b2ec07 or later. This exact version is the minimum_zig_version in build.zig.zon and the version CI pins (see Conformance and Testing). The nightly workflow additionally tracks Zig master as an early-warning canary; master is not a supported target (@hasField guards in build.zig paper over a couple of build- API drifts, but new breakages there are expected).

The library module links libc (.link_libc = true).

Adding es-parser as a dependency

Use zig fetch, which records the URL and content hash into your build.zig.zon:

# Pin to a release tag (recommended):
zig fetch --save https://github.com/ericsssan/es-parser/archive/refs/tags/v0.2.13.tar.gz

# …or track main:
zig fetch --save git+https://github.com/ericsssan/es-parser

This adds a dependency named es_parser, which exposes a module named es-parser (note the hyphen vs. underscore — the dependency name and the module name differ). Wire it up in build.zig:

const es_parser = b.dependency("es_parser", .{
    .target = target,
    .optimize = optimize,
});
my_module.addImport("es_parser", es_parser.module("es-parser"));

Then const es = @import("es_parser"); in your code. See API Reference for the surface.

Building this repository

zig build            # builds the library + runs zbc static analysis over src/
zig build test       # unit + lexer + parser + semantic + fuzz (regression) +
                     #   test262-parser-tests conformance

build.zig exposes the library as the es-parser module and wires five test modules into the test step — the in-src/ unit tests, tests/parser_test.zig, tests/lexer_test.zig, tests/semantic_test.zig, and the fuzz suite tests/fuzz_test.zig — plus the test262-parser-tests conformance runner (its submodule ships with the package).

The default zig build step also runs zbc — the author's Zig static analyzer (github.com/ericsssan/zbc, pinned as a URL dependency at v0.1.3) — over src/. zig build test does not run zbc.

Conformance steps

Each conformance runner is a separate ReleaseFast executable that imports a single shared ReleaseFast build of the parser. They take no arguments — each runs its built-in default fixture path:

zig build conformance-parser-tests   # tc39/test262-parser-tests (bundled; also in `test`)
zig build conformance-test262        # full tc39/test262
zig build conformance-babel          # Babel parser fixtures
zig build conformance-typescript     # TypeScript compiler tests (tests/cases)
zig build conformance-semantic       # parse + full semantic pipeline over the TS corpus

All but the first require initializing the corresponding git submodule first (.gitmodules): tests/conformance/test262, .../babel, .../typescript. conformance-semantic needs the typescript submodule — it sweeps the same tests/conformance/typescript/tests/cases corpus as conformance-typescript. The runners take no arguments, so the documented input set (e.g. the TypeScript runner's tests/cases, from which it derives baselines in the sibling tests/baselines/reference) is the canonical, built-in fixture path. See Conformance and Testing.

The current Zig build system drops trailing -- <args>, so the per-step default fixture path is canonical; the b.args override path in build.zig is guarded for older Zig only.

What ships in the package

build.zig.zon paths limits the published tarball to build.zig, build.zig.zon, CHANGELOG.md, src/, the two bundled conformance runners (parser_tests_runner.zig, semantic_runner.zig), the test262-parser-tests fixtures, and tests/fixtures. The large external corpora (full test262, Babel, TypeScript) are git submodules, not part of the distributed package.

Versioning

Semantic versioning; current version 0.2.13 (build.zig.zon). The CHANGELOG records per-release behavior changes — recent ones are TypeScript correctness fixes (typed catch bindings, named tuple members, invalid-regex recovery, generic arrow / constructor type parameters).

---

Next: Conformance and Testing · API Reference