compiler 0.0.2-preview.1
The Zena self-hosted compiler
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.jsonmanifest 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,
};
- zena-lang:wit-parser wit-parser.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|