compiler 0.0.2-preview.1
The Zena self-hosted compiler
compiler#
The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).
Usage#
Parsing a Single File#
Use compiler/parser to parse Zena source text into an AST (Module):
import { parse } from 'compiler/parser';
let ast = parse('export let answer = 42;', 'example.zena');
Loading and Checking a Program#
Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:
import {
createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';
let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
stdlibRoot,
packages,
});
let result = await compiler.compile({
entry: '/workspace/main.zena',
target: 'host',
});
let checked = checkCompilation(result);
Compiling a File to WebAssembly#
Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:
import { compileFile } from 'compiler/compile-file';
let ok = await compileFile({
entry: 'src/main.zena',
outPath: 'out/main.wasm',
stdlibRoot: '/stdlib',
});
Libraries#
compiler/compiler/compiler— compiler entry point (Compiler,createCompiler,checkCompilation,ProgramCheckResult)compiler/compile-file— end-to-end file compilation (compileFile,CompileFileOptions)compiler/tokenizer— lexer and token definitions (tokenize,Token,TokenType)compiler/parser— recursive-descent parser (parse,Parser)compiler/ast— AST node definitions (Node,Module,Statement,Expression,TypeAnnotation)compiler/visitor— AST traversal helpers (walk,Visitor)compiler/scope— lexical scope and symbol resolution (ScopeBuilder,ScopeResult,Symbol)compiler/checker— static type checker (checkModule,CheckResult)compiler/semantic-model— semantic queries over a checked module (SemanticModel)compiler/types— compiler type representations (Type,ClassType,FunctionType,typeToString)compiler/diagnostics— compiler diagnostics and source spans (Diagnostic,DiagnosticCode,DiagnosticSeverity,SourceSpan)compiler/package-manifest—zena-package.jsonmanifest and workspace loader (loadWorkspace,loadPackageMap)compiler/module-resolver— package and relative module specifier resolution (ModuleResolver,PackageConfig)compiler/library-loader— module graph loader (LibraryLoader,CompilerHost,SourceFile)compiler/codegen/binary-generator— WebAssembly GC binary emitter (BinaryGenerator)compiler/codegen/wat-generator— WebAssembly Text (WAT) emitter (WatGenerator)
License#
MIT
ZIR: the wasm backend (codegen/ir/)#
ZIR is a CFG+SSA mid-level IR. It is the compiler's only backend:
every reached function compiles AST → ZIR → wasm bytes. A lowering
bail (ZirUnsupported) is a compiler bug and fails the compile — never
a silent fallback.
Design doc: docs/design/ir.md
(section numbers below refer to it). Upstream of this directory,
../reachability/ (RTA) decides what
exists — reached functions, generic instantiations, vtables — and
populates the WasmModule model; ZIR only compiles what RTA reached.
Per-function pipeline#
Driven by module-generator.zena for each wasm.functions entry:
lowerWithTemplates(...) → IrBody (lowering.zena, template.zena)
runSimplify(body) (simplify.zena)
runBlockCleanup(body) (blockmerge.zena)
runGvn(body, new IrCfg(body)) (gvn.zena, cfg.zena)
runDce(body) (dce.zena)
verifyIr(body) → throws on any error (verifier.zena)
emitZirFunction(...) → wasm bytes (emit.zena)
Simplify may strand blocks (branch folding), which block cleanup then removes — the verifier rejects unreachable blocks, so those two are a pair. DCE runs last to sweep what folding and GVN left unused.
lowerWithTemplates is lowerFunction for most functions. A method of
a generic class with two siblings of the same family is instead copied
from a template its first two siblings taught (template.zena,
docs/design/template-zir.md). The copy equals what lowerFunction
would have produced; ZENA_TEMPLATE_CHECK=1 (set by
build:self-hosted and the portable execution runner) lowers it
directly too and fails on any difference, and ZENA_TEMPLATES=0 turns
templates off. A new lowering decision that depends on a
specialization's place in the module (its subclasses, its vtable) or
on the class a type parameter stands for (its ==, which class
provides a method) must be recorded for templates — the decisions
template-zir.md lists go through LoweringContext's queries,
lowerClassEquality and lowerAs — or be added to #templateGate.
The module pass is two-phase: every body is lowered, optimized, and
verified (and retained) before any is emitted. Between the phases, at
-O2, the module loop runs: an inline sweep (inline.zena), a
devirtualization sweep (devirt.zena), then constant propagation
(sccp.zena) per round, to a fixpoint with a round cap, re-cleaning
every changed body — inlining exposes the provenance devirtualization
reads, and the direct calls it makes are the next round's inline
sites. -O0
skips the cleanup passes; GVN runs at every level (emission quality
and the narrowing cast-dedup contract depend on it). The level arrives
as ZENA_OPT_LEVEL / -O<n> (docs/design/optimization-pipeline.md);
build:self-hosted and the fixpoint gate run -O2, so byte parity
polices the loop.
File map#
| File | Role |
|---|---|
ir.zena |
Instruction set (IrOp), IrBody flat-array encoding, operand decoding. Both decoders, appendValueOperands and rewriteValueOperands, dispatch on operandShapeOf's classification: a new op takes a shape there, and a new shape needs a case in both — keep them in sync. |
builder.zena |
IrBuilder: append-only construction API used by all lowering code. |
cfg.zena |
CFG + dominator tree (RPO) over an IrBody. |
lowering.zena |
FunctionLowerer — the core: SSA environment, expression/statement dispatch, calls, member access, constructors. Ends with the exported recursion seams (below). |
lowering-context.zena |
LoweringContext (cx) — the one shared state object every lowering module receives. cx.host is the FunctionLowerer coordinating the current function. |
control-flow.zena |
if/while/for/for-in/try/match statement shapes, let-conditions. |
contracts.zena |
The check a contract clause compiles to (docs/design/contracts.md): the condition, a branch, and a call to the standard library's $contractFailed with the clause's message. lower() emits a function's requires after its prologue; the loop shapes emit invariants at their headers. |
patterns.zena |
Pattern test/bind machinery (tuples, records, or-patterns, destructuring). |
operators.zena |
Binary/unary/compound operators, operator-method dispatch. |
equality.zena |
==/hashCode: case-class synthesizers, structural == on records and tuples (one $valueEq function per pair of operand types, registered by reachability; codegen/value-equality.zena holds the rules both share), erased eq diamond, eq/hash intrinsics. |
templates.zena |
Template literals and tagged templates. |
intrinsics.zena |
One function per @intrinsic; lowerIntrinsic is a pure router. |
scaffold.zena |
Helpers synthesized without an AST (string creation/hashing, wasi write). |
generators.zena |
The generator split pass (generators.md §5): presplit-lowers gen bodies, synthesizes frame structs + next() + Iterator<T> vtable globals between RTA and layout, rewrites bodies into dispatcher-loop state machines. |
async.zena |
The async split pass (async.md §3): the same treatment for async bodies — frame structs + step() + Resumable vtable globals, an eager ramp, a try_br failure-capture region, and the async-main export wrapper. Shares generators.zena's raw-IrBody helpers, liveness, edge rerouting, and try-region analysis. |
explode.zena |
Argument explosion (docs/design/argument-explosion.md), between reachability and the splits (which skip a suspending function's forwarder and split its core): beside each top-level function with a record or boxed tuple parameter (a tuple through a stand-in dispatch, RecordDispatchInfo.isTuple, read with struct_get) that is fields-only (every use reads a field or element or passes it whole to another fields-only parameter; bottom-up summary to a fixpoint) and available unpacked (some call passes a literal, or a core passes its own exploded parameter; top-down), adds a .core taking that record's fields (a class's own written constructor, unnamed or named, gets one for its factory, called from #constructInstance, and for its <ctor-init>/<ctor-body> phases (.name-suffixed for a named one), called from #allocateInstance with literal or forwarded super(...) records as fields; an instance method of a non-generic class gets one too, called from #lowerMethodCall when the call is direct, with the receiver ahead of the fields, while its vtable slot keeps the method); the original keeps its signature and becomes a forwarder that reads the fields and calls the core. A function whose record result some call only reads for its fields (and which has the fields on hand at some return) gets a core returning the fields as wasm results; marked calls (wasm.fieldsOnlyResultCalls) hold them as the record, and the forwarder builds the record for everyone else. A var record or tuple only read for its fields and only written fields (wasm.fieldHeldVars) is carried through joins as one value per field (addParams/envValues/applyParams in lowering-context.zena; applyParams runs after switchTo). #lowerDirectCallTo calls the core when some exploded argument is unpacked, reading any heap-record arguments' fields at the call. In the core the parameter binds to a record rebuilt from its fields, and recordDispatchRead answers reads off it from the fields (LoweringContext.explodedRecords), so DCE deletes it. |
simplify.zena |
Peephole pass, before GVN: constant folding (trap-preserving, NaN-guarded), algebraic identities, power-of-two strength reduction, constant-condition branch folding, static-subtype cast folds, and allocation forwarding (an immutable-field read off a struct_new, or an iface_pack's unpack, becomes the operand — the immutable tier of scalar replacement; DCE then deletes the unused allocation; and the reverse for tuples, whose identity is unobservable: a tuple struct_new built from every field of one value of its struct, in order, becomes that value). One id-order forward pass plus a final canonicalization sweep (inlining breaks id order). |
fold.zena |
The one table of compile-time evaluation, shared by simplify and SCCP: evalBinary/evalUnary (integer division and remainder never fold; float arithmetic folds only to a non-NaN), constOf, foldInstTo, and castOutcome — what a type test against a static type answers (1/0/-1; "never passes" rests on struct subtyping being a single chain and is withheld for nullable targets and abstract types). |
blockmerge.zena |
CFG cleanup: physically removes blocks unreachable after branch folding (compacts the block list, renumbers successor targets and tryJoin; a try whose join died, because its body can no longer complete, loses its tryJoin entry), and deletes block parameters every incoming edge passes the same value for — uses become the value, the argument leaves every branch record. Also forwards edges through a block whose only instruction is a br (arguments substituted for its parameters) and fuses a block into its sole predecessor when that predecessor just jumps to it; both keep loop exits where the emitter's fast exit placement can see them. Runs before and after simplify in the cleanup sequence. |
dce.zena |
Use-count DCE, one reverse-id pass (dead chains collapse because operand ids precede uses). Effects/trap table decides removability; loads need a non-null receiver. |
inline.zena |
-O2 inliner via IrBody.copyFrom: single-block callees splice in place; multi-block callees become new caller blocks with every ret a br to a continuation that takes the call's value and the rest of the call's block. Ids are pre-assigned before copying (within-block order need not match id order). Budgets: 12 real instructions straight-line; 64 when an argument makes inlining pay (a fresh allocation whose parameter does not escape, or a constant presence mask passed to an exploded core); 16 with control flow, and then only for a callee with one call site (its body moves) or ≤6 instructions — at 48 for everything the self-compile was 2.5× the -O1 size for no speed. Per-caller growth and per-callee caps per sweep. A multi-value callee gets one continuation parameter per result and its mv_get projections become those; a multi-value tail call copies as the call, its projections, and the branch. Callees with try_br or tail return never inline. |
escape.zena |
Per-parameter escape summaries, recomputed each -O2 round: a parameter escapes when the body stores, returns, throws, packs, identity-compares it, or passes it to an unknown callee or to a known one whose parameter escapes; casts and block params it flows into are followed. The inliner's argument rule reads them. |
licm.zena |
-O2, after the loop's rounds: moves pure, trap-free, non-allocating instructions whose operands are defined outside a natural loop to just before its header's immediate dominator's terminator. Immutable field loads, array lengths, fat-pointer unpacks, immutable globals, arithmetic, tests. Casts and allocations stay. |
sroa.zena |
-O2, each round after the devirtualization sweep: an allocation whose every use is a field read or write through it is deleted and each field becomes an SSA value — one parameter per field on every block the allocation's block strictly dominates, current values passed on every branch into them, reads replaced, writes dropped; block cleanup then deletes the parameters every edge agrees on. The mutable tier of scalar replacement (the immutable tier is simplify's forwarding); the iterator object's index becomes a loop-carried parameter. |
thread.zena |
-O2, after scalar replacement: jump threading through a block whose only instruction is a br_if on its own parameter — an inlined next()'s continuation branching on the done flag. Each predecessor passing a constant for the flag jumps straight to the arm it selects; an arm that reads the continuation's parameters gets parameters of its own and every edge into it passes the values. Block cleanup then removes the emptied continuation and the trivial parameters. |
specialize.zena |
-O2, each round after the cleanup that follows devirtualization: a function every direct call site hands a fat pointer packed around the same class gets a clone whose parameter is the instance, re-packed once at entry (simplify then forwards every unpack and cast against that pack); the sites pass the instance and name the clone; the original survives only as a value (vtable install, export, ref_func) or harvest deletes it. The clone's signature is appended to the laid-out type section by WasmModule.getSignatureLate. Single-class regime only. |
sccp.zena |
-O2, each round after the devirtualization sweep: sparse conditional constant propagation over the block-parameter SSA — values start unknown, edges start unexecuted, and a parameter meets only the arguments arriving on executed edges, so a branch whose condition is constant only because the arm that would change it is dead still folds. Rewrites constants in place, replaces constant parameters with a head-of-block constant, and turns one-live-edge branches into br; block cleanup removes the rest. |
harvest.zena |
After the loop, before any section is emitted: deletes functions and globals unreachable from the exports and the start function, following calls, ref_func, and global reads/writes/packs (a live vtable global keeps its installs, a live singleton its class vtable); rebinds indices the way layout does and recomputes the element segment. Fewer vtable globals means fewer devirtualization candidates, so the driver re-runs a round and harvests again while globals keep dying. Types are typeprune.zena's. |
deadslots.zena |
After harvest, before dead-field elimination, at -O1 and above: deletes the method slots of class and interface vtables that no struct_get in a surviving body reads, from the vtable structs and from every vtable global's funcs, so the next harvest removes the functions only those globals named. Liveness is per declaring struct and position (a subtype's vtable extends its supertype's); leading fields (slotGlobals), record tables, and any struct no global fills or some body allocates keep every field. A slot load whose value only feeds unused casts, which devirtualization leaves behind, is not a read and is deleted with its slot. |
deadfields.zena |
After harvest, before type pruning, at -O1 and above: deletes the fields of class structs that no struct_get in a surviving body names (a struct shares its superclass's field objects, so liveness is per declaring struct and index), turns their struct_sets into a non-null cast of a nullable receiver or a nop, and drops their operands from struct_new. Then deletes calls to functions left doing nothing (a setter whose field went). The driver runs DCE on the changed bodies and harvests again, and after type pruning re-runs WasmModule.layoutTypes, since fewer fields can make two groups structurally identical. Records are not candidates. |
typeprune.zena |
After harvest, before the type section is emitted: deletes the types nothing names any more, rooted from surviving signatures (functions, imports, tags), global types and initializers, and every body's type table, variable types and struct-naming refs; a live struct keeps its supertype and field types, an array its element, a signature its params and results. Keeps layout's order and rec groups (an emptied group disappears) and rebinds indices; a dead type gets index -1 so a missed reference fails loudly in the emitter. |
devirt.zena |
-O2: call_ref → call when the slot resolves — by provenance (vtable global read, iface_pack, <vtable> of a struct_new) or because every vtable global whose struct is the slot's owner or extends it installs the same function (closed-world single implementation, from the module's globals). Signatures must match exactly; multi-value slots rewrite like the rest. |
template.zena |
Template lowering (docs/design/template-zir.md): groups the methods of generic class specializations into families by method and pinned type arguments (pinOf), lowers each family's first two members in template mode (the builder appends one type entry per internType call), learns a recipe for every table entry that differs between them (an entity kind plus specialization keys generalized into KeyPatterns), records the decisions lowering makes from a specialization or a type argument's class (template-zir.md, Recorded decisions) as guards, and copies the rest: guards re-run, recipes resolved through RTA's tables and WasmModule.find*, the type log replayed through value interning. compare is check mode's body comparison. |
census.zena |
ZENA_ZIR_STATS counters for what the module loop left, just before emission: the surviving call_ref sites by what they dispatch through (class vtable, interface vtable, closure) and by how many implementations their slot has across the live vtable globals, the most-dispatched slots, the class-interface vtables and trampolines discovery built against those that survived, and the interface type tests on a value not held as the interface. The evidence for interprocedural type propagation (#421). |
propagate.zena |
Interprocedural type propagation (docs/design/type-propagation.md): for every reference value in the reached bodies, the set of struct types, vtable globals and functions that can reach it, solved with the call graph (a call_ref whose callee gains a function wires that function's edges and reaches it). Field nodes are per declaring struct, array element nodes flow into their supertype's, and anything from the host or an unmodelled instruction is top. At -O2 the one-function sites become direct calls after the module loop's rounds, and two more rounds inline through them (runPropagationDevirt, through devirt.zena's rewriteToCall); ZENA_PROPAGATE=0 turns that off, and ZENA_ZIR_STATS prints what the analysis resolves. |
gvn.zena |
Dominator-scoped value numbering; string keys + id-order walk keep it deterministic. |
verifier.zena |
Structural/type checks on IrBody; failures are loud compile errors. |
emit.zena |
SSA destruction: stack scheduling (#pushValue discipline), block-param copy coalescing, domtree stackifier, terminator streaming, init-discipline non-null local typing (live validator replay + removable asserts, ir.md §12.1). |
printer.zena |
ZIR-as-WAT-comments dump for debugging and snapshots. |
The import cycle (deliberate)#
This directory is a real module cycle: the per-construct modules import
lowerExpr/lowerExprRaw/lowerStmt/varDecl/throwStmt/
multiSource/lowerOptionalChainCoalesce as top-level fully-annotated
functions from
lowering.zena (the "Recursion seams" section at the end of that
file), and lowering-context.zena imports FunctionLowerer back. The
language's cycle rules (docs/design/import-cycles.md) allow this:
nominal types and fully-annotated functions cross back edges freely;
module-level values do not. When adding a new emission module,
follow the same pattern — import the seams, take cx as the first
parameter.
Invariants that bite#
- SSA via block params, not phis. The environment maps each variable symbol to its current value id; joins introduce block parameters for variables assigned in the joined regions; loop headers carry params for everything assigned anywhere in the loop (pre-scan).
- One non-SSA construct: mutable variables (
var_get/var_set, ir.md §5.1.1), each pinned to its own wasm local. They exist because a handler edge leaves from anywhere in a protected region and so can carry only entry-live values, which is not enough for locals thetrybody assigns. Every site that stores a new SSA value for a symbol intoenvmust callnoteVarWrite— a missed one leaves the handler reading a stale value, and nothing else will catch it. - A pair built around a null instance is not a null pair. An
interface value is a two-field struct and
I | nullis a nullable reference to it, sox == nulltests the POINTER. Packing a null throughiface_packproduces a non-null value that answers!= nulland then traps at the dispatch. A source the checker typedC | nullpacks under a null guard instead (#packInterfaceNullable) — the one path where a conversion,asor implicit, introduces control flow. The checker setsInterfaceAdaptation.sourceNullable; lowering must not re-derive it from the value's valtype, since a non-null-typed expression can sit in a nullable slot and the extra guard would be emission churn. - A
finallyis emitted once, and outside its own region. Every way out of the protected part — normal completion, the handler edge,return/break/continue— parks an exit code in a variable and branches to one dispatch block, which runs the finalizer and then replays that exit (exceptions.md, "Finally Compilation"). The dispatch lands outside the region because thetry_br's handler edge is one of its predecessors and the emitter streams that past theendof thetry_table. Emitting a copy per exit edge instead is not merely fatter: the copy on the normal path would sit INSIDE the region and re-enter itself if it threw.cx.finallyScopesis what routes the early exits, and truncating it at each dispatch is what makes nested finalizers run inside-out.usingis the region's second client, through the samelowerFinallyRegion— it supplies the rest of the block as the protected part and thedisposecall as the finalizer, with noTryExpressionsynthesized and no AST rewriting. So a change here moves resource release too, and the reverse:try/finally's snapshot plus the "emitted exactly once" WAT invariant are what say the shared region still emits what it did. - A split pass must re-enter try regions at every dispatch target.
Both suspension passes route every edge into a dispatch target through
a dispatcher that sits outside all user regions, so a target inside a
tryis entered unprotected unless the dispatcher branches to a freshtry_brcarrying that region's handler (async.md §6). Resume blocks are not the whole set: a suspending loop's header is a dispatch target too, and so is any merge block inside atryregion that is reached from two or more dispatcher arms (addRegionMergeTargetsingenerators.zena, e.g., an innertry/finallyorfor awaitfinalizer dispatch block whose handler gained a second predecessor fromreenterRegions). This fails silently — the success path is byte-for-byte plausible and only the throwing path skips the handler — so any change here needs a test that throws, on both sides of the suspension. - Determinism is a hard gate. Stage-2 byte parity (below) fails on
any iteration-order- or identity-dependent output. No wall-clock, no
randomness, no hash-order-dependent emission.
- It only gates output as a function of input, though: both stages
are separate processes, each compiling one module, so it cannot see
output that depends on what the process did earlier.
WasmTypeandWasmFunctionhash by a uid from a counter, so that counter ordered every hash container keyed by one — and left running across modules it made the fourth module in a process compile differently from the first, and often fail outright.ModuleGenerator.compilerestarts it per module;multi-entrypoint-codegen_test.zenaguards it. Any new process-global in codegen needs the same treatment, and a^varat module scope undercodegen/is the smell.
- It only gates output as a function of input, though: both stages
are separate processes, each compiling one module, so it cannot see
output that depends on what the process did earlier.
isValSubtypeignores nullability. It answers true forref null Xagainstref X(wasm-module.zena), soif (!isValSubtype(have, want)) { ref_cast }skips the non-null re-assert and emits invalid wasm. Conform a value withcx.conformToSlotorcx.reassertNonNull, which handle it.- Every operand load in emit goes through
#pushValue(except the copy-semantics#copyArgs). It enforces the stack schedule and throws on violations — those asserts catch real bugs; don't bypass them with rawemitLocalGet. - Bail messages name their pool. Keep the
[in <function>]suffix and the reason wording stable;ZENA_ZIR_STATS=1prints a histogram of bail reasons, and diagnosis relies on tagging a bail with the function/type names, rerunning, then reverting the tag.
Verification workflow#
Run from packages/compiler/. Wireit reruns what an edit under
zena/ affects; if it serves a stale result, a script is missing an
input, so fix its config (AGENTS.md, "Build System") rather than deleting
.wireit. To compile a probe without zena's compile cache, use
zena run --no-cache.
npm test # unit + syntax + semantics + execution + interop + fixpoint
npm run test:execution -- classes # filter one category
ZENA_ZIR_STATS=1 npm run build:self-hosted # self-compile; expect 0 bails
UPDATE_SNAPSHOTS=1 npm run test:unit # regenerate zir WAT snapshots
Snapshot tests fail on any emission change — regenerate and eyeball
the diff rather than fighting them. A change to how symbols are
allocated renames the _s<id> functions in
test-files/snapshots/console_target_js.snap (the id is the class or
interface declaration's symbol id); check that the regenerated diff
changes only those ids.
That is exactly why a snapshot alone cannot guard a property. The
regression and the innocent reformat produce the same failure, and
regenerating accepts both. When emission has to keep a property —
"this function does not allocate", "this shape still compiles to a
protected region" — assert the property too, with
src/test/wat-invariants.zena:
assertNoAllocation(wat, '$main', 'a try-assigned local is mirrored into a wasm local');
assertFunctionUses(wat, '$main', usesTry, 'the fixture should compile a try region');
assertFunctionOmits(wat, '$name', ops, why);
They scope to one function (a module-wide contains proves close to
nothing, since reachability drags in the stdlib) and name the property
in the failure. Pair them with a snapshot: the snapshot shows you what
changed, the invariant tells you whether it mattered. Write the
invariant so you have SEEN it fail — force the old lowering back, watch
the message, revert.
The final gate for backend changes is stage-2 byte parity: the compiler compiled by itself must byte-match the compiler that compiled it:
npm run build:self-hosted # writes out/cli-self.wasm
ZENA_GC_RESERVE_MB=1536 ZENA_COMPILER_WASM=out/cli-self.wasm \
../../target/release/zena build src/cli/main.zena -o out/cli-self2.wasm
cmp out/cli-self.wasm out/cli-self2.wasm
Note: compiler-source refactors change the self-compile input, so self-compile output is not a parity signal for them — byte-compare a fixed input program instead.
Debugging traps#
ZENA_EMIT_WAT=1writes a.watdump next to the output (huge; a second full generator pass — leave off otherwise).- Build with
-g(npm run zena -w @zena-lang/cli -- -g build ...) for a name section; then map a trap PC withwasm-tools print --print-offsetsand read the surrounding WAT against the source. - Suspected miscompile in the self-compile: add a temporary index-range env filter in module-generator's function loop and bisect — a culprit function falls out in ~15 iterations.
- Standalone lib-module builds (
zena build src/lib/X.zena) are a fast trap probe — they exercise imports. ZENA_TEST_PARALLELISM=Ncaps execution-test wasmtime fan-out (the default can exhaust machine memory).- A
zir unsupportedbail in a standard library or package function, especially one naming<error>(typeToStringof an error type), is usually a type error the compile did not report: a dependency's errors are dropped and its code generated anyway (#510).zena lint <file>checks the library on its own and printsdoes not check (<first error>);zena build <file> -o <out>.wasmprints every error.
Zena-authoring gotchas (recur constantly in this directory)#
new X(args).method()does not parse — bind to a local first.- i32
/promotes to f64; use>> 1/& 31for integer halving and masking. - A trailing
this.#bail(...)in an i32-returning function fails the missing-return check — writereturn this.#bailValue(...). - The ~30-arm
Expressionmatch trips Z2022 exhaustiveness false positives when several arms are added at once — the dispatch wildcard uses an if-chain for this reason. - Enums cast with
as i32when emitting bytes (Opcode.return_ as i32).
- zena-lang:wit-parser wit-parser.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|