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

5.4 KiB Raw
// Compilation targets and their capability flags.
//
// Each `--target` names a concrete host environment and breaks down into
// a fixed combination of `TargetFeatures`:
//
//   Target          | component | jsStrings | wasi  | zenaJsHost | zenaComponentHost
//   ----------------|-----------|-----------|-------|------------|------------------
//   core            | false     | false     | false | false      | false
//   js              | false     | true      | false | false      | false
//   zena-js         | false     | true      | false | true       | false
//   component       | true      | false     | true  | false      | false
//   zena-component  | true      | false     | true  | false      | true
//
// - `core`: core WebAssembly module with WTF-8 byte-backed strings and no
//   implicit host imports beyond `@external` declarations the program uses.
// - `js`: core WebAssembly module for any JavaScript engine supporting
//   `wasm:js-string` builtins and imported string constants, with zero
//   `@zena-lang/runtime` imports.
// - `zena-js`: extends `js` with `@zena-lang/runtime` host imports (console,
//   stack traces, host `URL`, number formatting/parsing, `zena:js`,
//   `zena:fetch`, `zena:time`, `zena:random`).
// - `component`: WebAssembly Component Model output targeting WASI 0.3 and
//   application WIT worlds, runnable on any WASI 0.3 host.
// - `zena-component`: extends `component` with `zena:host` WIT interfaces
//   provided by `zena-runtime` (stack traces, `zena:process`, `zena:wasm`,
//   `zena:extensions`, `zena:http` server). Default target of `zena build`.

/**
 * The capability flags a compilation target enables.
 */
export type TargetFeatures = {
  /** Emit a WebAssembly Component rather than a core module. */
  component: boolean,
  /** Use WTF-16 `externref` strings, `wasm:js-string` builtins, and imported string constants. */
  jsStrings: boolean,
  /** Expose WASI 0.3 standard library modules (`cli`, `fs`, `fetch`, `time`, `random`). */
  wasi: boolean,
  /** Enable `@zena-lang/runtime` JavaScript host imports (`console`, stack traces, host `URL`, etc.). */
  zenaJsHost: boolean,
  /** Enable `zena:host` component interfaces (`stack-trace`, `process`, `wasm`, `extensions`, `http-server`, `secrets`, `terminal`). */
  zenaComponentHost: boolean,
};

/** The targets a program can be built for, in `--target`'s own spelling. */
export function targetNames(): FixedArray<String> {
  return ["core", "js", "zena-js", "component", "zena-component"];
}

/** The target used when `--target` is omitted. */
export let defaultTarget = "zena-component";

/** Whether `target` is a target name the compiler knows. */
export function isKnownTarget(target: String): boolean {
  for (let t in targetNames()) {
    if (t == target) {
      return true;
    }
  }
  return false;
}

/** `--target`'s accepted spellings, for an error message. */
export function knownTargetsDescription(): String {
  var out = "";
  for (let t in targetNames()) {
    if (out != "") {
      out = out + ", ";
    }
    out = `${out}'${t}'`;
  }
  return out;
}

/**
 * The capability flags enabled by `target`. Throws on an unknown target.
 */
export function targetFeatures(target: String): TargetFeatures {
  if (target == "core") {
    return {
      component: false,
      jsStrings: false,
      wasi: false,
      zenaJsHost: false,
      zenaComponentHost: false,
    };
  }
  if (target == "js") {
    return {
      component: false,
      jsStrings: true,
      wasi: false,
      zenaJsHost: false,
      zenaComponentHost: false,
    };
  }
  if (target == "zena-js") {
    return {
      component: false,
      jsStrings: true,
      wasi: false,
      zenaJsHost: true,
      zenaComponentHost: false,
    };
  }
  if (target == "component") {
    return {
      component: true,
      jsStrings: false,
      wasi: true,
      zenaJsHost: false,
      zenaComponentHost: false,
    };
  }
  if (target == "zena-component") {
    return {
      component: true,
      jsStrings: false,
      wasi: true,
      zenaJsHost: false,
      zenaComponentHost: true,
    };
  }
  throw new Error(`Unknown target '${target}' (expected ${knownTargetsDescription()})`);
}

/**
 * Whether the target's output is a component rather than a core module.
 * A component is the only form that can reach WASI p2 or p3.
 */
export function targetEmitsComponent(target: String): boolean {
  return targetFeatures(target).component;
}

/**
 * Whether the target uses WebAssembly JS String builtins (`wasm:js-string`)
 * and imported string constants (`js` and `zena-js`).
 */
export function targetUsesJsStrings(target: String): boolean {
  return targetFeatures(target).jsStrings;
}

/** Whether the target provides WASI 0.3 interfaces (`component` and `zena-component`). */
export function targetUsesWasi(target: String): boolean {
  return targetFeatures(target).wasi;
}

/** Whether the target links `@zena-lang/runtime` host imports (`zena-js`). */
export function targetUsesZenaJsHost(target: String): boolean {
  return targetFeatures(target).zenaJsHost;
}

/** Whether the target links `zena:host` WIT interfaces (`zena-component`). */
export function targetUsesZenaComponentHost(target: String): boolean {
  return targetFeatures(target).zenaComponentHost;
}

/**
 * The module string literals are imported from on a target that uses JS
 * strings, unless `--imported-string-constants` names another. It is the
 * `importedStringConstants` the module must be compiled with.
 */
export let defaultImportedStringConstants = "_";
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19