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
17.4 KiB
Raw
import {
ValType, ValTypeRef, ValTypeRefNull, valTypeToOpcode,
} from '../wasm.zena';
import { IrBody, IrBlock, IrOp, IrRef, isIrTerminator } from './ir.zena';
import { simdInstruction } from '../../simd.zena';
import { TemplateRecorder } from './template.zena';
import { growable } from 'zena:core';
/**
* Compares ref targets by OBJECT IDENTITY, not type-section index:
* indices are all -1 until layout() runs, so index equality spuriously
* merges distinct types in bodies built pre-layout (the generator
* split pass builds bodies there). Identity is equivalent to index
* equality for laid-out types — see valTypeKeyEquals in
* wasm-module.zena for the same reasoning.
*/
export function valTypesStrictlyEqual(a: ValType, b: ValType): boolean {
return match (a) {
case ValTypeRef as ta: match (b) {
case ValTypeRef as tb: ta.target === tb.target
case _: false
}
case ValTypeRefNull as ta: match (b) {
case ValTypeRefNull as tb: ta.target === tb.target
case _: false
}
case _: valTypeToOpcode(a) == valTypeToOpcode(b)
};
}
/**
* ZIR construction API.
*
* The builder owns an IrBody under construction. Blocks are created with
* newBlock(); instructions append to the current block (switchTo) until a
* terminator is emitted, which closes the block. Types and refs are interned
* into the body's tables.
*
* The builder enforces only local well-formedness (no emission into a
* terminated or unselected block); global SSA invariants (dominance, branch
* arity) are the verifier's job.
*/
export final class IrBuilder {
body = new IrBody();
var #current: i32 = -1;
/**
* Template mode (template.zena): every `internType` call appends a
* type-table entry instead of interning, so two lowerings of one
* method name their types by call order and their tables line up
* entry for entry; the recorder collects lowering's guards. Null
* otherwise.
*/
var recorder: TemplateRecorder | null = null;
/**
* The result types of the function, while its returns are redirected
* to one block (`redirectReturns`); null otherwise.
*/
var #redirectedReturnTypes: GrowableArray<ValType> | null = null;
/** The block redirected returns go to, or -1 until one is emitted. */
var #redirectedReturnBlock: i32 = -1;
/** Total blocks created so far. */
numBlocks(): i32 {
return this.body.blocks.length;
}
/**
* Allocate a fresh block. It is not current until switchTo(b) is called.
*/
newBlock(): i32 {
let idx = this.body.blocks.length;
this.body.blocks.push(new IrBlock());
return idx;
}
/**
* Select `block` as the insertion target for subsequent emissions. Fails if
* `block` has already received a terminator instruction.
*/
switchTo(block: i32): void {
if (block < 0 || block >= this.body.blocks.length) {
throw new Error('switchTo: no such block');
}
if (this.#isTerminated(block)) {
throw new Error('switchTo: block already terminated');
}
this.#current = block;
}
/** Current insertion target (-1 before first switchTo). */
currentBlock(): i32 {
return this.#current;
}
/**
* Adds a parameter to a block. Parameters may be added until the block
* gains its terminator (on-demand params are how loop-carried values
* appear during lowering).
*/
blockParam(block: i32, type: ValType): i32 {
if (this.#isTerminated(block)) {
throw new Error('blockParam: block already terminated');
}
let blk = this.body.blocks[block];
let inst = this.#newInst(IrOp.param, this.internType(type),
blk.params.length, -1, block);
blk.params.push(inst);
return inst;
}
internType(type: ValType): i32 {
let table = this.body.typeTable;
if (this.recorder != null) {
table.push(type);
return table.length - 1;
}
var i = 0;
while (i < table.length) {
if (valTypesStrictlyEqual(table[i], type)) {
return i;
}
i += 1;
}
table.push(type);
return table.length - 1;
}
addRef(ref: IrRef): i32 {
this.body.refTable.push(ref);
return this.body.refTable.length - 1;
}
// -- Mutable variables (ir.md §5.1) ----------------------------------
/** Allocates a fresh mutable variable of type `vt`; returns its id. */
newVar(vt: ValType): i32 {
this.body.varTypes.push(vt);
return this.body.varTypes.length - 1;
}
/** Reads a mutable variable at its declared type. */
varGet(varId: i32): i32 {
return this.#emitInCurrent(IrOp.var_get,
this.internType(this.body.varTypes[varId]), -1, varId);
}
/** Writes `value` into a mutable variable. */
varSet(varId: i32, value: i32): void {
this.#emitInCurrent(IrOp.var_set, -1, value, varId);
}
// -- Low-level emission ----------------------------------------------
/** Emits a value-producing instruction with inline operands. */
emit(op: IrOp, type: ValType, a: i32, b: i32): i32 {
return this.#emitInCurrent(op, this.internType(type), a, b);
}
/** Emits a void instruction with inline operands. */
emitVoid(op: IrOp, a: i32, b: i32): i32 {
return this.#emitInCurrent(op, -1, a, b);
}
/** Copies `values` into the extra pool, returning the start index. */
pushExtra(values: GrowableArray<i32>): i32 {
let start = this.body.extra.length;
for (let v in values) {
this.body.extra.push(v);
}
return start;
}
/** Copies [argc, args...] into the extra pool. */
pushArgList(args: GrowableArray<i32>): i32 {
let start = this.body.extra.length;
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
return start;
}
// -- Typed helpers ------------------------------------------------------
constI32(value: i32, type: ValType): i32 {
return this.emit(IrOp.const_i32, type, value, -1);
}
constI64(value: i64, type: ValType): i32 {
this.body.constI64.push(value);
return this.emit(IrOp.const_i64, type, this.body.constI64.length - 1, -1);
}
constF64(value: f64, type: ValType): i32 {
this.body.constF64.push(value);
return this.emit(IrOp.const_f64, type, this.body.constF64.length - 1, -1);
}
/** f32 constants share the f64 pool (f32→f64 widening is exact). */
constF32(value: f64, type: ValType): i32 {
this.body.constF64.push(value);
return this.emit(IrOp.const_f32, type, this.body.constF64.length - 1, -1);
}
/**
* The all-zero vector. Wasm has no `v128` counterpart to `i32.const`
* — the only vector constant is the 16-byte `v128.const` — so a zero
* `v128` is an instruction with a sixteen-byte immediate rather than
* a pooled literal.
*/
constV128Zero(type: ValType): i32 {
let instr = simdInstruction('v128.const');
if (instr == null) {
throw new Error('v128.const is missing from the SIMD table');
}
let imm = growable<i32>([instr.opcode]);
var i = 0;
while (i < 16) {
imm.push(0);
i += 1;
}
return this.emit(IrOp.simd_const, type, -1, this.pushExtra(imm));
}
binary(op: IrOp, type: ValType, x: i32, y: i32): i32 {
return this.emit(op, type, x, y);
}
callFunc(funcRef: i32, args: GrowableArray<i32>, resultType: ValType | null): i32 {
let argsIdx = this.pushArgList(args);
if (resultType == null) {
return this.#emitInCurrent(IrOp.call, -1, argsIdx, funcRef);
}
return this.#emitInCurrent(IrOp.call, this.internType(resultType),
argsIdx, funcRef);
}
/**
* Multi-result call: the call itself produces no single value; one
* mv_get projection per result is emitted immediately after it, in
* ascending result order (emission relies on that adjacency+order).
*/
callFuncMulti(funcRef: i32, args: GrowableArray<i32>, resultTypes: GrowableArray<ValType>): GrowableArray<i32> {
let argsIdx = this.pushArgList(args);
let call = this.#emitInCurrent(IrOp.call, -1, argsIdx, funcRef);
let projections = new Array<i32>(resultTypes.length);
for (var k = 0; k < resultTypes.length; k += 1) {
projections.push(this.#emitInCurrent(IrOp.mv_get,
this.internType(resultTypes[k]), call, k));
}
return projections;
}
/**
* A wide-arithmetic instruction: two i64 results, low half first,
* read through mv_get projections under the same contract as a
* multi-result call (emitted immediately after, ascending order).
* `operands` is the pair for the multiplies and the
* [lhsLo, lhsHi, rhsLo, rhsHi] quadruple for add128/sub128.
*/
wideArith(op: IrOp, operands: GrowableArray<i32>, resultType: ValType): GrowableArray<i32> {
let producer = if (operands.length == 2) {
this.#emitInCurrent(op, -1, operands[0], operands[1])
} else {
this.#emitInCurrent(op, -1, this.pushExtra(operands), -1)
};
let projections = new Array<i32>(2);
for (var k = 0; k < 2; k += 1) {
projections.push(this.#emitInCurrent(IrOp.mv_get,
this.internType(resultType), producer, k));
}
return projections;
}
/** Multi-value return. */
retMulti(values: GrowableArray<i32>): void {
if (this.#redirectedReturnTypes != null) {
this.br(this.#returnTarget(), values);
return;
}
let idx = this.body.extra.length;
this.body.extra.push(values.length);
for (let v in values) {
this.body.extra.push(v);
}
this.#emitInCurrent(IrOp.ret_multi, -1, idx, -1);
}
/** array.new_data: bytes [offset, offset+length) of data segment
* `dataIndex` as a fresh array of the given (byte) array type. */
arrayNewData(offset: i32, length: i32, dataIndex: i32, typeRef: i32,
resultType: ValType): i32 {
let idx = this.body.extra.length;
this.body.extra.push(offset);
this.body.extra.push(length);
this.body.extra.push(dataIndex);
return this.#emitInCurrent(IrOp.array_new_data,
this.internType(resultType), idx, typeRef);
}
/** Multi-result call_ref; same projection contract as callFuncMulti. */
callRefMulti(callee: i32, args: GrowableArray<i32>, resultTypes: GrowableArray<ValType>): GrowableArray<i32> {
let start = this.body.extra.length;
this.body.extra.push(callee);
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
let call = this.#emitInCurrent(IrOp.call_ref, -1, start, -1);
let projections = new Array<i32>(resultTypes.length);
for (var k = 0; k < resultTypes.length; k += 1) {
projections.push(this.#emitInCurrent(IrOp.mv_get,
this.internType(resultTypes[k]), call, k));
}
return projections;
}
/** call_ref through a funcref value: extra = [callee, argc, arg*]. */
callRef(callee: i32, args: GrowableArray<i32>, resultType: ValType | null): i32 {
let start = this.body.extra.length;
this.body.extra.push(callee);
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
if (resultType == null) {
return this.#emitInCurrent(IrOp.call_ref, -1, start, -1);
}
return this.#emitInCurrent(IrOp.call_ref, this.internType(resultType),
start, -1);
}
// -- Terminators ---------------------------------------------------------
br(target: i32, args: GrowableArray<i32>): void {
let idx = this.body.extra.length;
this.body.extra.push(target);
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
this.#emitInCurrent(IrOp.br, -1, idx, -1);
}
brIf(cond: i32, thenTarget: i32, thenArgs: GrowableArray<i32>,
elseTarget: i32, elseArgs: GrowableArray<i32>): void {
let idx = this.body.extra.length;
this.body.extra.push(thenTarget);
this.body.extra.push(thenArgs.length);
for (let v in thenArgs) {
this.body.extra.push(v);
}
this.body.extra.push(elseTarget);
this.body.extra.push(elseArgs.length);
for (let v in elseArgs) {
this.body.extra.push(v);
}
this.#emitInCurrent(IrOp.br_if, -1, cond, idx);
}
/** try_br: a = tag ref, b = [bodyTarget, argc, arg*, catchTarget,
* argc, arg*]. Terminator; both edges carry block arguments.
* Returns the instruction id so lowering can record the region's
* join in `body.tryJoin` once it exists. */
tryBr(tagRef: i32, bodyTarget: i32, bodyArgs: GrowableArray<i32>,
catchTarget: i32, catchArgs: GrowableArray<i32>): i32 {
let idx = this.body.extra.length;
this.body.extra.push(bodyTarget);
this.body.extra.push(bodyArgs.length);
for (let v in bodyArgs) {
this.body.extra.push(v);
}
this.body.extra.push(catchTarget);
this.body.extra.push(catchArgs.length);
for (let v in catchArgs) {
this.body.extra.push(v);
}
return this.#emitInCurrent(IrOp.try_br, -1, tagRef, idx);
}
ret(value: i32): i32 {
if (this.#redirectedReturnTypes != null) {
this.br(this.#returnTarget(), growable<i32>([value]));
return -1;
}
return this.#emitInCurrent(IrOp.ret, -1, value, -1);
}
/**
* From here on, a return branches to one block that takes the
* returned values as its parameters, of the function's result
* `types`. A function with postconditions checks them there and then
* returns (docs/design/contracts.md). The block is made by the first
* return to reach it, so a function that never returns has none.
*/
redirectReturns(types: GrowableArray<ValType>): void {
this.#redirectedReturnTypes = types;
this.#redirectedReturnBlock = -1;
}
/**
* Stops redirecting returns. Answers the block they went to, or -1
* when none was emitted.
*/
endReturnRedirect(): i32 {
this.#redirectedReturnTypes = null;
return this.#redirectedReturnBlock;
}
#returnTarget(): i32 {
if (this.#redirectedReturnBlock < 0) {
let block = this.newBlock();
for (let type in this.#redirectedReturnTypes as GrowableArray<ValType>) {
this.blockParam(block, type);
}
this.#redirectedReturnBlock = block;
}
return this.#redirectedReturnBlock;
}
/**
* `ret_call`: a tail call to a known function, encoded exactly as
* `call` but terminating the block and producing no value — the
* callee's results are this function's results
* (docs/design/tail-calls.md). The caller owes the wasm rule that
* the callee's results are subtypes of this function's.
*/
retCall(funcRef: i32, args: GrowableArray<i32>): void {
let argsIdx = this.pushArgList(args);
this.#emitInCurrent(IrOp.ret_call, -1, argsIdx, funcRef);
}
/** `ret_call_ref`: the same, through a funcref. Encoded exactly as
* `call_ref` — [callee, argc, arg*] — and terminating. */
retCallRef(callee: i32, args: GrowableArray<i32>): void {
let start = this.body.extra.length;
this.body.extra.push(callee);
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
this.#emitInCurrent(IrOp.ret_call_ref, -1, start, -1);
}
/** yield_: a = yielded value, b = [resumeTarget, argc, arg*].
* Suspension terminator for presplit generator bodies; the split
* pass rewrites every yield before emission. */
yieldTo(value: i32, resumeTarget: i32, args: GrowableArray<i32>): void {
let idx = this.body.extra.length;
this.body.extra.push(resumeTarget);
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
this.#emitInCurrent(IrOp.yield_, -1, value, idx);
}
/** await_: a = awaited future, b = [resumeTarget, argc, arg*].
* Suspension terminator for presplit async bodies; the split pass
* rewrites every await before emission. */
awaitTo(future: i32, resumeTarget: i32, args: GrowableArray<i32>): i32 {
let idx = this.body.extra.length;
this.body.extra.push(resumeTarget);
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
return this.#emitInCurrent(IrOp.await_, -1, future, idx);
}
retVoid(): void {
if (this.#redirectedReturnTypes != null) {
this.br(this.#returnTarget(), new Array<i32>(0));
return;
}
this.#emitInCurrent(IrOp.ret, -1, -1, -1);
}
unreachable(): void {
this.#emitInCurrent(IrOp.unreachable, -1, -1, -1);
}
/** throw: extra = [argc, arg*], b = tag ref. Terminator. */
throwWithTag(args: GrowableArray<i32>, tagRef: i32): void {
let idx = this.body.extra.length;
this.body.extra.push(args.length);
for (let v in args) {
this.body.extra.push(v);
}
this.#emitInCurrent(IrOp.throw, -1, idx, tagRef);
}
/**
* Finishes construction and returns the body. Structural validity
* (all blocks terminated, SSA invariants) is checked by the verifier,
* not here, so tests can construct deliberately broken bodies.
*/
finish(): IrBody {
this.#current = -1;
return this.body;
}
// -- Internals ------------------------------------------------------
#isTerminated(block: i32): boolean {
let insts = this.body.blocks[block].insts;
if (insts.length == 0) {
return false;
}
return isIrTerminator(this.body.op(insts[insts.length - 1]));
}
#newInst(op: IrOp, typeId: i32, a: i32, b: i32, block: i32): i32 {
let {body} = this;
body.opcode.push(op as i32);
body.typeId.push(typeId);
body.a.push(a);
body.b.push(b);
body.instBlock.push(block);
return body.opcode.length - 1;
}
#emitInCurrent(op: IrOp, typeId: i32, a: i32, b: i32): i32 {
if (this.#current < 0) {
throw new Error('emit: no current block');
}
if (this.#isTerminated(this.#current)) {
throw new Error('emit: current block already terminated');
}
let inst = this.#newInst(op, typeId, a, b, this.#current);
this.body.blocks[this.#current].insts.push(inst);
return inst;
}
}
- 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 |
|
|