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.1 KiB Raw
/**
 * What a compiler is, and what one compile is.
 *
 * A `Compiler` holds the host, the standard library root, the package
 * map and the flags the checker reads, and lives across compiles. A
 * compile names an entry point and a target. Several compiles, at
 * several targets, share one warm compiler.
 */

import { Module } from './ast.zena';
import { ComponentEntryWrapper } from './component-entry.zena';
import { PackageConfig } from './module-resolver.zena';
import { HashMap } from 'zena:collections';

/**
 * Where a compiler reads source from, what packages exist, and what the
 * checker is told.
 *
 * The stdlib (the `zena` package) is always included: the caller gives
 * `stdlibRoot` and configures only its own packages.
 *
 * A flag belongs here when it changes what parsing or checking
 * *produces*, because then two compiles that disagree on it cannot
 * share a file's `CheckResult` — the result would answer the other
 * one's question. A flag that only changes what is emitted belongs to
 * the compile, or to the generator.
 */
export type CompilerOptions = {
  /**
   * Absolute path to the stdlib's zena source directory, e.g.
   * "/path/to/packages/stdlib/zena". Required because the self-hosted
   * compiler does not yet embed the stdlib sources.
   */
  stdlibRoot: String,

  /**
   * User package map: name → PackageConfig, typically a workspace's,
   * loaded from its manifests by `loadWorkspace()`. The `zena` package is
   * added automatically from `stdlibRoot` and does not belong here.
   */
  packages: Map<String, PackageConfig>,

  /**
   * Keep a partial AST for source the parser can recover from, instead
   * of letting the error abort the compile. The errors still get
   * reported, on `SourceFile.parseErrors`; this only decides whether the
   * rest of the file is still analyzed. Tools that answer questions
   * about source being typed want it on, builds want it off.
   */
  recoverFromParseErrors?: boolean,

  /** Emit source locations for `__LOCATION__` defaults. */
  emitLocations?: boolean,

  /** Warn when an `as` cast targets the type the expression already has. */
  warnUnnecessaryCasts?: boolean,
};

/**
 * What the checker was told, beyond the program itself.
 *
 * A `ProgramCheckResult` only carries forward into a compile that
 * agrees on all of it. The target is here because a path names a
 * different library on each target; the other two because they change
 * what a check produces.
 */
export type CheckSettings = {
  target: String,
  emitLocations: boolean,
  warnUnnecessaryCasts: boolean,
};

/** Whether two checks asked the same question, and so may share results. */
export function sameCheckSettings(a: CheckSettings, b: CheckSettings): boolean {
  return a.target == b.target &&
    a.emitLocations == b.emitLocations &&
    a.warnUnnecessaryCasts == b.warnUnnecessaryCasts;
}

/**
 * One compile: an entry point and a target.
 *
 * Only `target` changes what the checker produces, and a compiler keeps
 * one file set per target, so compiles that differ only here still
 * share everything they can.
 */
export type CompileOptions = {
  /**
   * The entry point, as a canonical path: an absolute file path, or a
   * "package:name" specifier.
   */
  entry: String,

  /** Compilation target; see targets.zena for the names. */
  target: String,

  /**
   * Opaque version tag for the entry, compared against the loader's
   * cached copy: a cached entry with a different version is re-loaded.
   * The compiler does not interpret it — the language service passes
   * the editor's document version.
   */
  version?: String,

  /**
   * The component target's entry wrapper writer, when the driver has one
   * that knows more than the compiler alone: given the entry's path and
   * syntax, the wrapper to load beside it, or null. Absent means the
   * default, which writes `main`'s wrapper (component-entry.zena); a
   * driver compiling against a declared world passes wit-module-synth's,
   * which also wraps the world's async exports, because the compiler
   * does not link the WIT parser.
   */
  componentWrapperSynth?:
      (entryPath: String, ast: Module) => ComponentEntryWrapper | null,
};
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19