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

4.0 KiB Raw
import { CodeGenerator } from './code-generator.zena';
import { ByteBuffer } from 'zena:core';
import { Program } from '../program.zena';
import { BinaryEmitter } from './binary-emitter.zena';
import { ModuleGenerator } from './module-generator.zena';
import { TypeInterner } from '../types.zena';
import { emitComponent, ComponentShape, ImportTypeEncoder } from './component-emitter.zena';
import { defaultImportedStringConstants, targetEmitsComponent } from '../targets.zena';

/**
 * The stateless entry point for WebAssembly code generation.
 * Creates a module builder and delegates the compilation of the given program.
 */
export final class BinaryGenerator implements CodeGenerator<ByteBuffer> {
  target: String;
  zirStats: boolean;
  /**
   * Emit the `name` custom section. Off by default: the section is
   * pure debug metadata and, for a small program, the largest thing in
   * the module — 9.9KB of a 34KB hello-world. `-g` turns it on.
   */
  debugNames: boolean;

  backendName(): String { return 'wasm'; }

  /**
   * The runtime memory module's bytes, for the component target. The
   * driver compiles them once per build (`compileComponentRuntimeModule`)
   * and hands them here; a component whose program uses linear memory
   * cannot be emitted without them, and `emitComponent` says so.
   */
  var runtimeMemoryModule: ByteBuffer | null = null;

  /**
   * The WIT import encoder, injected beside the runtime module by
   * drivers that emit components. Codegen calls it through this
   * indirection so it does not link the WIT parser itself.
   */
  var importEncoder: ImportTypeEncoder | null = null;

  /**
   * Emit the wide-arithmetic proposal's instructions (`i64.mul_wide_u`
   * and friends) instead of the 32-bit-halves sequences that mean the
   * same thing. Off by default: wasmtime, wasmi, JavaScriptCore and
   * SpiderMonkey implement the proposal, V8 does not yet, and the
   * stdlib has to run under `node`. ZENA_WIDE_ARITHMETIC=1 turns it on.
   */
  var wideArithmetic: boolean = false;

  /** `WasmModule.debugContracts`. */
  var debugContracts: boolean = false;

  /** `WasmModule.importedStringConstants`. */
  var importedStringConstants = defaultImportedStringConstants;

  /** `ModuleGenerator.compactImports`. */
  var compactImports = false;

  /** `ModuleGenerator.templates`. */
  var templates = true;

  /** `ModuleGenerator.templateCheck`. */
  var templateCheck = false;

  /** `ModuleGenerator.propagate`. */
  var propagate = true;

  /** The checker's interned types, passed on to the module; see `WasmModule.interner`. */
  var interner: TypeInterner | null = null;

  /** Optimization level, forwarded to ModuleGenerator. */
  optLevel: i32;

  new(this.target = "core", this.zirStats = false, this.debugNames = false,
      this.optLevel = 1);

  generate(program: Program): ByteBuffer {
    let bb = new ByteBuffer();
    let emitter = new BinaryEmitter(bb, this.debugNames);
    let generator = new ModuleGenerator(program, emitter, this.target, this.zirStats,
        this.optLevel);
    generator.wideArithmetic = this.wideArithmetic;
    generator.debugContracts = this.debugContracts;
    generator.importedStringConstants = this.importedStringConstants;
    generator.compactImports = this.compactImports;
    generator.templates = this.templates;
    generator.templateCheck = this.templateCheck;
    generator.propagate = this.propagate;
    generator.interner = this.interner;
    generator.importEncoder = this.importEncoder;
    generator.compile();
    // A component is the same core module with a wrapper around it: the
    // module is embedded verbatim, and the component contributes only
    // types, instantiation and the lift/lower adapters.
    if (targetEmitsComponent(this.target)) {
      let shape = generator.componentShape;
      if (shape == null) {
        throw new Error(
          "The component target produced no component shape — " +
          "ModuleGenerator.compile did not collect one."
        );
      }
      return emitComponent(bb, shape, this.runtimeMemoryModule);
    }
    return bb;
  }
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19