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

3.8 KiB Raw
/**
 * The component target's runtime memory module, compiled on demand.
 *
 * A component whose program touches linear memory embeds a second core
 * module owning the memory and the allocator
 * (docs/design/component-emission.md, 1.3). Its source is fixed —
 * `component-runtime/memory.zena`, under the standard library root but
 * in neither manifest — so this is a small, deterministic nested
 * compile, on the `core` target of the compiler that is already
 * running the enclosing build. Drivers call it once per component
 * build and hand the bytes to `BinaryGenerator`, or pass the path to a
 * copy they built earlier; a driver that does neither gets a loud error
 * from `emitComponent` the moment a program needs memory, not a
 * component that fails validation.
 *
 * This lives beside the generators rather than in `compiler.zena`
 * because it needs both halves — the compiler to check the source and
 * `BinaryGenerator` to emit it — and `compiler.zena` deliberately does
 * not depend on codegen.
 */

import { ByteBuffer } from 'zena:core';
import { Compiler, checkCompilation } from '../compiler.zena';
import { DiagnosticSeverity } from '../diagnostics.zena';
import { Program, CompilationUnit } from '../program.zena';
import { BinaryGenerator } from './binary-generator.zena';
import { HashMap } from 'zena:collections';

/** The runtime module's entry, relative to the standard library root. */
let runtimeEntry = "component-runtime/memory.zena";

/**
 * The bytes this process has already built, by standard library root.
 *
 * The module's source is fixed and the compile deterministic, so two
 * component builds in one process against the same standard library
 * want the same bytes, and the second compile is work for nothing. It
 * is not a small amount of work: compiling it costs about 1.2s, which
 * on a trivial program is more than compiling the program.
 *
 * This only helps a process that builds more than one component — a
 * test runner, or a batch compile. A single `zena build` still pays
 * once, and the way to fix that is to build these bytes ahead of time
 * rather than to cache them here.
 */
let cachedByStdlibRoot = new Map<String, ByteBuffer>();

/**
 * Compile the runtime memory module; the finished core-module bytes.
 *
 * It compiles on the compiler running the enclosing build, which
 * already has the host and the standard library root it needs — only
 * the target differs. On `core`, `zena:memory` is the real
 * free-list allocator rather than the module that delegates to the
 * component's memory, which is the whole reason this is a second
 * compile rather than part of the first.
 */
export async function compileComponentRuntimeModule(
  compiler: Compiler,
  stdlibRoot: String
): Future<ByteBuffer> {
  if (let (true, cached) = cachedByStdlibRoot.get(stdlibRoot)) {
    return cached;
  }
  let compResult = await compiler.compile({
    entry: `${stdlibRoot}/${runtimeEntry}`,
    target: "core",
  });
  let checkResults = checkCompilation(compResult);
  for (let diag in checkResults.diagnostics) {
    if (diag.severity == DiagnosticSeverity.Error) {
      // Program code cannot reach this compile; an error here means the
      // stdlib or the compiler itself regressed.
      throw new Error(
          "the component runtime memory module failed to compile: " +
          diag.message);
    }
  }
  let entryAst = compResult.entry.ast;
  let units = new Array<CompilationUnit>();
  var entryUnit: CompilationUnit | null = null;
  for (let file in compResult.files) {
    let res = checkResults.results[file.path];
    if (res != null) {
      let unit = {ast: file.ast, model: res.model};
      units.push(unit);
      if (file.ast.path == entryAst.path) {
        entryUnit = unit;
      }
    }
  }
  let bytes = new BinaryGenerator("core", false)
      .generate(new Program(units, entryUnit));
  cachedByStdlibRoot[stdlibRoot] = bytes;
  return bytes;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19