compiler 0.0.2-preview.1

The Zena self-hosted compiler

Readme Files Dependencies Versions

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.json manifest 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

11.4 KiB Raw
import { ValType, ImportDesc } from "./wasm.zena";

import { WasmFunction, WasmGlobal } from './wasm-module.zena';
import { ByteBuffer } from 'zena:core';

/**
 * One import of the import section, and the function or global it binds,
 * which is how `ModuleGenerator` reorders the import lists when the plan
 * moves it. The memory import binds neither.
 */
export final class ImportItem(module: String, name: String, desc: ImportDesc,
    target: WasmFunction | WasmGlobal | null)

export interface WasmEmitter {
  emitModuleStart(): void;
  emitTypeSectionStart(count: i32): void;
  emitRecGroupStart(count: i32): void;
  emitRecGroupEnd(): void;
  emitFunctionTypeStart(index: i32): void;
  emitFunctionTypeParamsStart(count: i32): void;
  emitFunctionTypeParam(type: ValType): void;
  emitFunctionTypeResultsStart(count: i32): void;
  emitFunctionTypeResult(type: ValType): void;
  emitFunctionTypeEnd(): void;
  /**
   * `isFinal` says no type in this module declares this struct as a
   * supertype, so it is emitted in the `sub final` form. Wasmtime's
   * `ref.test`/`ref.cast` against a final type is an inline type-index
   * comparison with no fallback to the `is_subtype` libcall; see
   * docs/design/struct-finality.md.
   */
  emitStructTypeStart(index: i32, name: String | null, superTypeIndex: i32,
      isFinal: boolean): void;
  emitStructTypeFieldsStart(count: i32): void;
  emitStructTypeField(type: ValType, isMutable: boolean): void;
  emitStructTypeEnd(): void;
  emitTypeSectionEnd(): void;
  emitFunctionSectionStart(count: i32): void;
  emitFunctionDefinition(typeIndex: i32): void;
  emitFunctionSectionEnd(): void;

  /**
   * `count` is the number of entries, each one call to `emitImport`,
   * `emitImportGroup` or `emitImportTypeGroup`. The two groups are the
   * compact import section proposal's: a module written once for a run
   * of names and types, and a module and type written once for a run of
   * names (see import-plan.zena).
   */
  emitImportSectionStart(count: i32): void;
  emitImport(item: ImportItem): void;
  emitImportGroup(module: String, items: GrowableArray<ImportItem>): void;
  emitImportTypeGroup(module: String, desc: ImportDesc, items: GrowableArray<ImportItem>): void;
  emitImportSectionEnd(): void;

  emitGlobalSectionStart(count: i32): void;
  emitGlobal(type: ValType, isMutable: boolean): void;
  emitGlobalEnd(): void;
  emitGlobalSectionEnd(): void;

  emitExportSectionStart(count: i32): void;
  emitExport(name: String, func: WasmFunction): void;
  emitExportGlobal(name: String, globalIndex: i32): void;
  emitExportTag(name: String, tagIndex: i32): void;
  emitExportSectionEnd(): void;
  emitElementSection(indices: GrowableArray<i32>): void;
  
  emitTagSectionStart(count: i32): void;
  emitTagDefinition(index: i32, typeIndex: i32): void;
  emitTagSectionEnd(): void;
  
  emitStartSection(funcIndex: i32): void;
  
  emitCodeSectionStart(count: i32): void;
  emitFunctionCodeStart(func: WasmFunction): void;
  emitFunctionCodeEnd(func: WasmFunction): void;
  emitCodeSectionEnd(): void;
  
  emitModuleEnd(): void;

  emitFunctionSignatureStart(name: String, typeIndex: i32): void;
  emitFunctionLocalsStart(locals: GrowableArray<ValType>): void;
  emitFunctionEnd(): void;
  
  // Control flow
  emitUnreachable(): void;
  emitBlock(resultType: ValType): void;
  emitLoop(resultType: ValType): void;
  emitIf(resultType: ValType): void;
  emitElse(): void;
  emitEnd(): void;
  emitBr(depth: i32): void;
  emitBrIf(depth: i32): void;
  emitThrow(tagIndex: i32): void;
  emitTryTableCatch(resultType: ValType, tagIndex: i32, destDepth: i32): void;

  emitReturn(): void;
  emitCall(target: WasmFunction): void;
  /** `return_call`: a tail call, replacing this frame. tail-calls.md. */
  emitReturnCall(target: WasmFunction): void;
  emitI32Const(value: i32): void;
  emitF32Const(value: f64): void;
  emitF64Const(value: f64): void;
  emitBooleanConst(value: boolean): void;
  emitStringConst(value: String): void;
  emitDrop(): void;

  // GC operations
  emitStructNew(typeIndex: i32): void;
  emitStructNewDefault(typeIndex: i32): void;
  emitStructGet(typeIndex: i32, fieldIndex: i32): void;
  emitStructSet(typeIndex: i32, fieldIndex: i32): void;
  emitRefCastEq(): void;
  emitRefCastEqNull(): void;
  /** `ref.cast (ref null struct)`: to a value that is some struct, such
   * as a union of tuples. */
  emitRefCastStructNull(): void;
  /** `ref.cast (ref null none)`: passes only null, so it fails for every other value. */
  emitRefCastNullNone(): void;
  emitRefCast(typeIndex: i32): void;
  emitRefCastNull(typeIndex: i32): void;
  emitRefTest(typeIndex: i32): void;
  emitRefTestNull(typeIndex: i32): void;
  emitRefNull(heapType: i32): void;
  emitAnyConvertExtern(): void;
  emitExternConvertAny(): void;


  // Variables
  emitLocalGet(index: i32): void;
  emitLocalSet(index: i32): void;
  emitLocalTee(index: i32): void;
  emitGlobalGet(index: i32): void;
  emitCallRef(typeIndex: i32): void;
  /** `return_call_ref`: a tail call through a funcref. */
  emitReturnCallRef(typeIndex: i32): void;
  emitRefFunc(index: i32): void;
  emitRefEq(): void;
  emitRefIsNull(): void;
  emitRefAsNonNull(): void;
  /**
   * Emits a ref.as_non_null that exists only because `local` is
   * declared nullable, remembering where it landed. If the local later
   * graduates to its non-null type (init-discipline typing, ir.md
   * §12.1), dropAssertsForLocals removes the emission from the
   * function's output — binary bytes and WAT text alike, so the text
   * never shows an assert the binary does not pay for.
   */
  emitRemovableRefAsNonNull(local: i32): void;
  /**
   * Marks which locals graduated non-null; called after the function
   * body, before emitFunctionCodeEnd assembles the output. Removable
   * asserts recorded against a graduated local are dropped.
   */
  dropAssertsForLocals(graduated: GrowableArray<boolean>): void;
  emitGlobalSet(index: i32): void;
  
  // Binary operations
  emitI32Add(): void;
  emitI32Sub(): void;
  emitI32Mul(): void;
  emitI32DivS(): void;
  emitI32DivU(): void;
  emitI32Eq(): void;
  emitI32Eqz(): void;
  emitI32Ne(): void;
  emitI32LtS(): void;
  emitI32LtU(): void;
  emitI32LeS(): void;
  emitI32LeU(): void;
  emitI32GtS(): void;
  emitI32GtU(): void;
  emitI32GeS(): void;
  emitI32GeU(): void;
  emitI32RemS(): void;
  emitI32RemU(): void;
  emitI32And(): void;
  emitI32Or(): void;
  emitI32Xor(): void;
  emitI32Shl(): void;
  emitI32ShrS(): void;
  emitI32ShrU(): void;
  emitI32Clz(): void;
  emitI32Ctz(): void;
  emitI32Popcnt(): void;
  
  emitF64Add(): void;
  emitF64Sub(): void;
  emitF64Mul(): void;
  emitF64Div(): void;
  emitF64Eq(): void;
  emitF64Ne(): void;
  emitF64Lt(): void;
  emitF64Le(): void;
  emitF64Gt(): void;
  emitF64Ge(): void;
  emitF64ConvertI32S(): void;

  emitF32Add(): void;
  emitF32Sub(): void;
  emitF32Mul(): void;
  emitF32Div(): void;
  emitF32Eq(): void;
  emitF32Ne(): void;
  emitF32Lt(): void;
  emitF32Le(): void;
  emitF32Gt(): void;
  emitF32Ge(): void;
  emitF32ConvertI32S(): void;

  // Memory operations
  emitMemorySize(): void;
  emitMemoryGrow(): void;
  emitI32Load(align: i32, offset: i32): void;
  emitI32Store(align: i32, offset: i32): void;
  emitI32Load8U(align: i32, offset: i32): void;
  emitI32Store8(align: i32, offset: i32): void;
  emitI64Load(align: i32, offset: i32): void;
  emitI64Store(align: i32, offset: i32): void;
  emitF32Load(align: i32, offset: i32): void;
  emitF32Store(align: i32, offset: i32): void;
  emitF64Load(align: i32, offset: i32): void;
  emitF64Store(align: i32, offset: i32): void;

  /**
   * SIMD instructions. `opcode` is the number following the `0xFD`
   * prefix; the emitter writes the prefix and encodes the opcode as a
   * ULEB128 (it exceeds one byte past 127, which most of the vector set
   * does). Five hooks rather than 236 methods, because the operand
   * shapes are all the instructions differ by at this level —
   * `simdInstruction` in lib/simd.zena is where a name becomes a number.
   */
  emitSimd(opcode: i32): void;
  /** Lane-immediate forms: extract/replace lane. */
  emitSimdLane(opcode: i32, lane: i32): void;
  /** Memory forms: v128.load/store and their splat/extend variants. */
  emitSimdMem(opcode: i32, align: i32, offset: i32): void;
  /** Memory forms carrying a lane index too: v128.load8_lane & co. */
  emitSimdMemLane(opcode: i32, align: i32, offset: i32, lane: i32): void;
  /**
   * The two instructions with a 16-byte immediate: `v128.const`, whose
   * bytes are the vector in little-endian lane order, and
   * `i8x16.shuffle`, whose bytes are lane selectors. Both take their
   * opcode from the table like everything else rather than hard-coding
   * one here.
   */
  emitSimdBytes(opcode: i32, bytes: GrowableArray<i32>): void;

  /**
   * A wide-arithmetic instruction (`0xFC` + `opcode`, one of 19..22).
   * Only reached when `WasmModule.wideArithmetic` is on — otherwise
   * lowering never builds the ZIR op that gets here.
   */
  emitWideArith(opcode: i32): void;

  /** `isFinal` as for `emitStructTypeStart`. */
  emitArrayType(index: i32, elementType: ValType, isMutable: boolean,
      superTypeIndex: i32, isFinal: boolean): void;
  emitMemorySection(minPages: i32): void;
  emitExportMemory(name: String, memIndex: i32): void;
  emitDataCountSection(count: i32): void;
  emitDataSection(datas: GrowableArray<ByteBuffer>, rawDatas: GrowableArray<ByteBuffer>): void;
  emitArrayNew(typeIndex: i32): void;
  emitArrayNewDefault(typeIndex: i32): void;
  emitArrayNewFixed(typeIndex: i32, count: i32): void;
  emitArrayNewData(typeIndex: i32, dataIndex: i32): void;
  emitArrayGet(typeIndex: i32): void;
  emitArrayGetU(typeIndex: i32): void;
  emitArrayGetS(typeIndex: i32): void;
  emitArraySet(typeIndex: i32): void;
  emitArrayLen(): void;
  emitArrayCopy(destTypeIndex: i32, srcTypeIndex: i32): void;

  emitI64Const(value: i64): void;
  emitI64Add(): void;
  emitI64Sub(): void;
  emitI64Mul(): void;
  emitI64DivS(): void;
  emitI64DivU(): void;
  emitI64RemS(): void;
  emitI64RemU(): void;
  emitI64And(): void;
  emitI64Or(): void;
  emitI64Xor(): void;
  emitI64Shl(): void;
  emitI64ShrS(): void;
  emitI64ShrU(): void;
  emitI64Eqz(): void;
  emitI64Eq(): void;
  emitI64Ne(): void;
  emitI64LtS(): void;
  emitI64LtU(): void;
  emitI64LeS(): void;
  emitI64LeU(): void;
  emitI64GtS(): void;
  emitI64GtU(): void;
  emitI64GeS(): void;
  emitI64GeU(): void;
  emitI64Clz(): void;
  emitI64Ctz(): void;
  emitI64Popcnt(): void;
  emitF32Neg(): void;
  emitF64Neg(): void;
  emitF32Ceil(): void;
  emitF64Ceil(): void;
  emitF32Floor(): void;
  emitF64Floor(): void;
  emitF32Trunc(): void;
  emitF64Trunc(): void;
  emitF32Sqrt(): void;
  emitF64Sqrt(): void;
  emitF32Min(): void;
  emitF64Min(): void;
  emitF32Max(): void;
  emitF64Max(): void;
  emitF32Copysign(): void;
  emitF64Copysign(): void;
  emitF32Abs(): void;
  emitF64Abs(): void;
  emitF32Nearest(): void;
  emitF64Nearest(): void;
  emitI64TruncSatF32S(): void;
  emitI64TruncSatF32U(): void;
  emitI64TruncSatF64S(): void;
  emitI64TruncSatF64U(): void;
  emitI32TruncSatF32S(): void;
  emitI32TruncSatF32U(): void;
  emitI32TruncSatF64S(): void;
  emitI32TruncSatF64U(): void;
  emitI64ReinterpretF64(): void;
  emitF64ReinterpretI64(): void;
  emitI32ReinterpretF32(): void;
  emitF32ReinterpretI32(): void;
  emitI64ExtendI32S(): void;
  emitI64ExtendI32U(): void;
  emitI32WrapI64(): void;
  emitF32ConvertI64S(): void;
  emitF64ConvertI64S(): void;
  emitF32ConvertI32U(): void;
  emitF64ConvertI32U(): void;
  emitF32ConvertI64U(): void;
  emitF64ConvertI64U(): void;
  emitF64PromoteF32(): void;
  emitF32DemoteF64(): void;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19