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
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 = "_";
- 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 |
|
|