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
14.3 KiB
Raw
/**
* @file
*
* The component target's entry wrapper: a module the compiler writes
* beside the entry, for the functions whose values reach the host
* through a typed `task.return`.
*
* A callback-lifted export hands its result to the host through
* `task.return`, a canonical builtin whose canon entry carries the
* result's type. The core function that calls it has to be declared
* at that type, and nothing in the standard library can name what a
* particular program's functions return. So the declarations are
* written here, per program, into a small module loaded beside the
* entry. The module imports the program's functions, declares
* `task.return` at each one's result type, and exports a wrapper per
* function that starts it and hands its future to the driver together
* with the typed return to call once the future settles. The entry
* adapter (`codegen/ir/component-adapters.zena`) calls a wrapper in
* place of the function.
*
* This file writes the wrapper for `main` when its value needs one: an
* async `main` returning a flat scalar or a `String`, and a synchronous
* `main` returning a `String`, which the entry cannot return itself
* because a `string` result is read out of linear memory. The choice
* is made from the entry's syntax alone, the annotation on `main`, so
* the wrapper can be loaded in the same compile as the entry, before
* anything is checked. A declared world's async exports need the WIT,
* which the compiler does not link: `wit-module-synth.zena` writes
* those wrappers, with the same shape, and the driver injects it
* (`CompilerOptions.componentWrapperSynth`).
*
* See docs/design/component-async-exports.md.
*/
import { StringBuilder, join } from 'zena:core';
import {
Module, FunctionDeclaration, VariableDeclaration, FunctionExpression,
IdentifierPattern, NamedTypeAnnotation, ClassDeclaration, MethodDefinition,
Identifier
} from './ast.zena';
import { toKebabName } from './codegen/component-emitter.zena';
/** What the wrapper's path adds to the entry's. */
let wrapperSuffix = '.component-entry.zena';
/** Whether `path` names a wrapper this module wrote. */
export function isComponentEntryPath(path: String): boolean {
return path.endsWith(wrapperSuffix);
}
/** The wrapper's path for the entry at `entryPath`. */
export function componentEntryPathFor(entryPath: String): String {
return entryPath + wrapperSuffix;
}
/** The core function name the adapter looks for in the wrapper. */
export let componentEntryRunName = 'run';
/**
* What a wrapper adds to a world export's name to name the function
* the adapter calls: `describe` is implemented by `describe_export`.
* WIT names are kebab-case, so no camelCase rendering of one contains
* an underscore and the suffix cannot collide.
*/
export let componentExportSuffix = '_export';
/**
* The component export name a wrapper's base name stands for. A plain
* name is the kebab-case of the Zena spelling (`describe`). A
* resource's function carries the resource and the kind in the base,
* joined by double underscores (no WIT-derived name contains one):
* `surface__constructor`, `surface__method__onFrame` and
* `surface__static__create` name the canonical ABI's
* `[constructor]surface`, `[method]surface.on-frame` and
* `[static]surface.create`. The empty string for a base with no
* kebab-case rendering.
*/
export function componentExportNameOf(base: String): String {
let parts = base.split('__');
if (parts.length == 1) {
return toKebabName(base);
}
let resource = toKebabName(parts[0]);
if (resource == '') {
return '';
}
if (parts.length == 2 && parts[1] == 'constructor') {
return '[constructor]' + resource;
}
if (parts.length == 3 && (parts[1] == 'method' || parts[1] == 'static')) {
let member = toKebabName(parts[2]);
if (member == '') {
return '';
}
return `[${parts[1]}]${resource}.${member}`;
}
return '';
}
/** The wrapper base name for a resource's function: see
* `componentExportNameOf`. */
export function resourceWrapperBase(resource: String, kind: String,
member: String): String {
if (kind == 'constructor') {
return resource + '__constructor';
}
return `${resource}__${kind}__${member}`;
}
/**
* The suffix of a declared world's synchronous export wrapper — one
* whose parameters or result are richer than the flat scalars and
* strings a program export lifts on its own. Lifted directly, no
* callback: the value comes back from the call, through a return
* area when it flattens past one core value.
*/
export let componentSyncExportSuffix = '_export_sync';
/**
* A wrapper to load beside the entry. `entrySpecifier` is how the
* wrapper's source imports the entry, and `entryPath` is the loaded
* entry's path, which the loader pins that specifier to so the entry
* is not loaded a second time under a differently spelled path.
*/
export final class ComponentEntryWrapper {
path: String;
source: String;
entrySpecifier: String;
entryPath: String;
new(this.path, this.source, this.entrySpecifier, this.entryPath);
}
/**
* The flat scalar types a `main` may return through the wrapper:
* the ones that lift as one core value, and that a synthesized module
* can name without importing anything.
*/
let scalarResults = [
'bool', 'i8', 'u8', 'i16', 'u16', 'i32', 'u32', 'i64', 'u64',
'f32', 'f64'
];
function isScalarResult(name: String): boolean {
for (let s in scalarResults) {
if (s == name) { return true; }
}
return false;
}
/**
* The result `main` returns through the wrapper, as the wrapper spells
* its type: a flat scalar's name, `String`, or the empty string when
* `main` needs no wrapper.
*
* An async `main` annotated `Future<T>` needs one for a flat scalar or
* a `String` `T`. A synchronous `main` needs one only for `String`: a
* scalar is known when it returns, and the entry adapter returns it
* itself (ir/component-adapters.zena).
*/
function wrapperResultOf(func: FunctionExpression) {
let annotation = func.returnType;
if (!(annotation is NamedTypeAnnotation)) { return ''; }
if (!func.isAsync) {
return if (isStringResult(annotation)) 'String' else '';
}
if (annotation.name == 'Future') {
let args = annotation.typeArguments;
if (args != null) {
if (args.length == 1) {
let arg = args[0];
if (arg is NamedTypeAnnotation) {
if (isStringResult(arg)) {
return 'String';
}
if (arg.typeArguments == null) {
if (isScalarResult(arg.name)) {
return arg.name;
}
}
}
}
}
}
return '';
}
/** Whether `annotation` is `String`. */
function isStringResult(annotation: NamedTypeAnnotation) {
return annotation.name == 'String' && annotation.typeArguments == null;
}
/**
* The result the module's exported `main` returns through the wrapper,
* or the empty string: see `wrapperResultOf`. Both spellings count:
* `export async function main()` and `export let main = async () => ...`.
*/
export function mainWrapperResultOf(ast: Module): String {
let main = exportedMainOf(ast);
return if (main == null) '' else wrapperResultOf(main as FunctionExpression);
}
/** Whether the module exports an async `main`: the entry the
* component lifts on its own, whichever way a declared world spells
* it. */
export function hasAsyncMain(ast: Module): boolean {
let main = exportedMainOf(ast);
return main != null && (main as FunctionExpression).isAsync;
}
/**
* Whether the entry's implementation of an export is `async`: the
* function `name` at the top level, in either spelling, or, with
* `className`, the method or static `member` of that class. False
* when there is no such function, which the compile reports in its
* own words. The wrapper for an export that returns nothing asks, to
* hand an async implementation's future to the driver and to call a
* synchronous one outright.
*/
export function exportedFunctionIsAsync(ast: Module, name: String,
className: String, member: String): boolean {
for (let stmt in ast.body) {
if (className == '') {
if (stmt is FunctionDeclaration) {
if (stmt.name.name == name) {
return stmt.func.isAsync;
}
} else if (stmt is VariableDeclaration) {
let pattern = stmt.pattern;
if (pattern is IdentifierPattern) {
if (pattern.name == name) {
let init = stmt.init;
if (init is FunctionExpression) {
return init.isAsync;
}
}
}
}
} else if (stmt is ClassDeclaration) {
if (stmt.name.name == className) {
for (let m in stmt.body) {
if (m is MethodDefinition) {
let mname = m.name;
if (mname is Identifier) {
if (mname.name == member) {
return m.isAsync;
}
}
}
}
}
}
}
return false;
}
/**
* Whether the entry declares class `className` with a static `member`.
* The wrapper for a plugin kind's `create` asks, to write the static
* itself when the class leaves it out.
*/
export function classHasStatic(ast: Module, className: String, member: String): boolean {
for (let stmt in ast.body) {
if (stmt is ClassDeclaration) {
if (stmt.name.name == className) {
for (let m in stmt.body) {
if (m is MethodDefinition) {
let mname = m.name;
if (mname is Identifier) {
if (mname.name == member && m.isStatic) {
return true;
}
}
}
}
}
}
}
return false;
}
/** The module's exported `main` function, in either spelling, or
* null. */
function exportedMainOf(ast: Module): FunctionExpression | null {
for (let stmt in ast.body) {
if (stmt is FunctionDeclaration) {
if (stmt.exported) {
if (stmt.name.name == 'main') {
return stmt.func;
}
}
} else if (stmt is VariableDeclaration) {
if (stmt.exported) {
let pattern = stmt.pattern;
if (pattern is IdentifierPattern) {
if (pattern.name == 'main') {
let init = stmt.init;
if (init is FunctionExpression) {
return init;
}
}
}
}
}
}
return null;
}
/** The last path segment. */
function baseName(path: String) {
var from = 0;
for (var i = 0; i < path.length; i += 1) {
if (path.getByteAt(i) == 47) { from = i + 1; } // '/'
}
return path.sliceBytes(from, path.length);
}
/** How a wrapper beside the entry imports it. */
export function componentEntrySpecifierFor(entryPath: String): String {
return './' + baseName(entryPath);
}
/** The comment every wrapper opens with. */
export function renderWrapperHeader(sb: StringBuilder): void {
sb.append('// Written by the compiler for the component target: the ');
sb.append('wrappers whose\n');
sb.append('// values reach the host through a typed `task.return`, ');
sb.append('declared here at\n');
sb.append('// each one\'s result type and called once its future ');
sb.append('settles. See\n');
sb.append('// docs/design/component-async-exports.md.\n');
}
/**
* The names a main wrapper for `result` imports from `zena:wasi`.
* `finishTask` hands an async main's value to the driver; a `String`
* is staged into linear memory for the typed return to read, and a
* synchronous main's wrapper tells the driver it has returned.
*/
export function mainWrapperAbiImports(result: String, isAsync: boolean): GrowableArray<String> {
let names = new Array<String>();
if (isAsync) {
names.push('finishTask');
}
if (result == 'String') {
names.push('stagedMark');
names.push('stageString');
names.push('releaseStagedFrom');
if (!isAsync) {
names.push('markReturned');
}
}
return names;
}
/**
* The typed return for `main`'s `result`, and `run`, which calls main
* and returns its value: through the driver for an async main, once
* the future settles, and at once for a synchronous one. Appended to a
* wrapper whose imports already bring in `main` and the names
* `mainWrapperAbiImports` lists.
*
* A scalar's `task.return` takes the value. A `String`'s is typed by
* the WIT `string`, so its parameters are the staged bytes' address and
* length, and the staging is freed once the return has read it.
*/
export function renderMainWrapper(sb: StringBuilder, result: String,
isAsync: boolean): void {
let isString = result == 'String';
if (isString) {
sb.append('@external("canon", "task.return#main", "return:#string")\n');
sb.append('declare function taskReturnMain(ptr: i32, len: i32): void;\n\n');
sb.append('function returnMain(value: String): void {\n');
sb.append(' let mark = stagedMark();\n');
sb.append(' let (ptr, len) = stageString(value);\n');
sb.append(' taskReturnMain(ptr, len);\n');
sb.append(' releaseStagedFrom(mark);\n');
sb.append('}\n\n');
} else {
sb.append('@external("canon", "task.return#main")\n');
sb.append('declare function taskReturnMain(value: ').append(result)
.append('): void;\n\n');
}
let returnFn = if (isString) 'returnMain' else 'taskReturnMain';
sb.append('export function ').append(componentEntryRunName)
.append('(): void {\n');
if (isAsync) {
sb.append(' finishTask<').append(result).append('>(main(), (value: ')
.append(result).append('): void => {\n');
sb.append(' ').append(returnFn).append('(value);\n');
sb.append(' });\n');
} else {
sb.append(' ').append(returnFn).append('(main());\n');
sb.append(' markReturned();\n');
}
sb.append('}\n');
}
/**
* The wrapper for the entry at `entryPath` with syntax `ast`, or null
* when the program's `main` is synchronous, returns nothing or
* returns something other than a flat scalar.
*/
export function componentEntryWrapperFor(
entryPath: String,
ast: Module
): ComponentEntryWrapper | null {
let result = mainWrapperResultOf(ast);
if (result == '') {
return null;
}
let isAsync = hasAsyncMain(ast);
let specifier = componentEntrySpecifierFor(entryPath);
let sb = new StringBuilder();
renderWrapperHeader(sb);
sb.append('import { main } from \'').append(specifier).append('\';\n');
sb.append('import { ');
sb.append(join(mainWrapperAbiImports(result, isAsync), ', '));
sb.append(' } from \'zena:wasi\';\n\n');
renderMainWrapper(sb, result, isAsync);
return new ComponentEntryWrapper(componentEntryPathFor(entryPath),
sb.toString(), specifier, entryPath);
}
- 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 |
|
|