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
38.5 KiB
Raw
/**
* Compiling one source file to a module on disk: what `zc` does, as a
* function other programs can call. The compiler's own command line
* (`src/cli/main.zena`) and the `zena` command line both use it.
*
* It reads source and writes the module through `zena:fs`, so the caller
* decides what it can reach through its preopens: the entry and its
* package manifest are read relative to the working directory, and the
* standard library from `stdlibRoot`.
*/
import { getEnv } from 'zena:cli';
import { ByteBuffer, StringBuilder } from 'zena:core';
import { JsonBuilder } from 'zena:json';
import { readFile, readFileBytes, writeFileBytes, writeFile, exists } from 'zena:fs';
import { CompilerHost } from './library-loader.zena';
import { PackageConfig, stdlibIdToRelativeFile } from './module-resolver.zena';
import { loadWorkspace } from './package-manifest.zena';
import {
Compiler, CompilerOptions, ProgramCheckResult, createCompiler, CompileOptions,
checkCompilation, withBuiltinPackages, buildStdlibConfig, setCheckAllBodies
} from './compiler.zena';
import { DiagnosticCode, DiagnosticSeverity, SourceSpan, SyntaxError } from './diagnostics.zena';
import { BinaryGenerator } from './codegen/binary-generator.zena';
import { WatGenerator } from './codegen/wat-generator.zena';
import { Program, CompilationUnit } from './program.zena';
import { Module } from './ast.zena';
import { nowMs, performance } from './time.zena';
import {
defaultImportedStringConstants, defaultTarget, isKnownTarget,
knownTargetsDescription, targetEmitsComponent, targetUsesJsStrings
} from './targets.zena';
import { compileComponentRuntimeModule } from './codegen/component-runtime.zena';
import { reportCensus } from './census.zena';
import { markTypes, setCensusEnabled } from './types.zena';
import { makeImportEncoder } from './codegen/wit-imports.zena';
import {
isWitModulePath, synthesizeWitModule, synthesizeExportWrapper,
declaredPackageNamespaces
} from './wit-module-synth.zena';
import { ComponentEntryWrapper } from './component-entry.zena';
import { readWitSource, readWitDocument } from './wit-source.zena';
import { WitDocument, witDiagnostic } from 'zena-lang:wit-parser/document';
import { parseSyntax } from 'zena-lang:wit-parser';
import { Ast as WitAst } from 'zena-lang:wit-parser/parser';
import { checkExtensionViews } from './extension-views.zena';
import { directoryNames } from './fs-host.zena';
import { HashMap } from 'zena:collections';
export { defaultTarget } from './targets.zena';
/**
* "-O" levels: 0, 1, 2, and s (size — the loop with budgets down,
* currently equal to 2). Returns -1 on anything else.
*/
export function parseOptLevel(text: String): i32 {
if (text == "0") { return 0; }
if (text == "1") { return 1; }
if (text == "2") { return 2; }
if (text == "s") { return 2; }
return -1;
}
/** What `optLevel` means when a request leaves it out. */
export let defaultOptLevel = 1;
/** What to compile, where to put it, and how. */
export type CompileFileOptions = {
/** The source file, relative to the working directory. */
entry: String,
/** Where to write the module; a `.wat` path writes the text form. */
outPath: String,
target?: String,
/**
* Compile a test suite: a file without its own `main` gets one that
* runs `tests` through `zena:test`'s `runAndReport`.
*/
testMode?: boolean,
/** Print a report of how long each compiler phase took. */
time?: boolean,
/** A WIT file or directory declaring the component's world. */
witPath?: String,
/** Which world in `witPath`, when it declares several. */
worldName?: String,
/**
* WIT files or directories the program's extensions are written to.
* Each interface in them that `worldName` imports or exports must be
* the program's view of it (`extension-views.zena`), or the compile
* fails naming what differs.
*/
extensionWitPaths?: Array<String>,
/**
* The module string literals are imported from on the `js` target:
* the `importedStringConstants` the host compiles the module with.
* `defaultImportedStringConstants` when absent; an error on any other
* target.
*/
importedStringConstants?: String,
/**
* Group imports by module, and by type within a module, in the
* encodings of the compact import section proposal
* (`ModuleGenerator.compactImports`). Only on a target that emits a
* core module.
*/
compactImports?: boolean,
/** Emit a name section, so traps name functions. */
debugNames?: boolean,
warnUnnecessaryCasts?: boolean,
/** 0, 1 or 2; see docs/design/optimization-pipeline.md. */
optLevel?: i32,
/** Where the standard library's `zena/` directory is. */
stdlibRoot?: String,
/**
* The absolute path of the working directory, the workspace root. With
* it, a path dependency outside the workspace (`../zena/packages/lib`)
* is read by its absolute path; without it, or when it is empty, such a
* dependency cannot be read.
*/
projectRoot?: String,
/**
* Where fetched packages are, as `zena pkg fetch` stores them: each
* package's source archive unpacked in `sources/<CID>`. Without it, or
* when it is empty, the packages `zena-lock.json` pins are not
* available.
*/
packageCache?: String,
/** Print "Compiling ..." and "Success: wrote ..." lines. */
progress?: boolean,
/**
* Called with each source file's path just before the compiler reads
* it, as the compiler names it: relative to the working directory, or
* under `stdlibRoot`. A compile cache records these to know when its
* entry is stale.
*/
onRead?: (path: String) => void,
/**
* A component's runtime memory module, already compiled, as the path
* to its `.wasm`. Absent or empty means compile one
* (`component-runtime.zena`), as an empty `witPath` means no declared
* world.
*
* Its bytes do not vary with the program — core module 0 has no
* imports, and the program module imports its exports at the
* component level — so a driver that can keep them between builds
* should, because compiling them is about two thirds of a small
* component build. A caller passing this is asserting the bytes were
* built from the same standard library this compile is reading.
*/
runtimeMemoryPath?: String,
};
/** The default `onRead`: a compile nothing is caching ignores it. */
function ignoreRead(path: String) {}
/**
* The host the compiler reads source through: files from the working
* directory, `zena:` modules from the standard library, and WIT-backed
* modules synthesized from their WIT.
*/
class FileHost implements CompilerHost {
testMode: boolean;
stdlibRoot: String;
onRead: (path: String) => void;
/**
* The entry of the compile in progress: in test mode, the one file
* that gets a `main`.
*/
var entryPath = "";
/** The WIT-backed packages' source, once it has been read. */
var packagesWit = "";
new(this.testMode, this.stdlibRoot, this.onRead);
/**
* The file a module's source is read from, as `onRead` names it: a
* `zena:` module is a file under the standard library's root.
*/
fileOf(path: String): String {
return if (path.startsWith("zena:")) {
`${this.stdlibRoot}/${stdlibIdToRelativeFile(path)}`
} else {
path
};
}
async readFile(path: String): Future<String> {
// A WIT-backed package's module: no file exists — the source is
// synthesized from the package's WIT.
if (isWitModulePath(path)) {
return await synthesizeWitModule(this, path, this.packagesWit);
}
let actualPath = this.fileOf(path);
let onRead = this.onRead;
onRead(actualPath);
let content = await readFile(actualPath);
if (this.testMode && path == this.entryPath) {
// A file that declares its own entry point is left alone. This runs
// before the source is parsed, so the test is textual; what matters is
// that it be narrow enough not to fire on ordinary prose or data.
//
// It used to look for "let main", "main =" or "main(" anywhere in the
// file, which matched far more than declarations: `let mainScope`, and
// — inside a string literal — the `domain(` of a URL pattern. A suite
// that merely mentioned one got no entry point and then failed with
// "Failed to find `main` export", naming nothing in the file that
// caused it. See tests/test/wrapper-main-substring_test.zena.
if (content.contains("export let main ") ||
content.contains("export let main=") ||
content.contains("export function main(")) {
return content;
}
// Asynchronous, because the runner awaits each test: a test's
// body may be.
return "import {runAndReport} from 'zena:test';\n" +
content +
"\nexport async function main(): Future<i32> {\n return await runAndReport(tests, (s: String): void => {\n console.log(s);\n });\n}\n";
}
return content;
}
async listDir(path: String): Future<Array<String> | null> {
return await directoryNames(path);
}
}
// Load the packages of the workspace in the working directory, from its
// manifests (`loadWorkspace`). No workspace is
// fine — standalone files need only stdlib and relative imports — but a
// malformed one throws loudly, and so does one that pins a package the cache
// does not have.
async function loadPackages(
host: CompilerHost,
projectRoot: String | null,
packageCache: String | null
): Future<HashMap<String, PackageConfig>> {
let packages = await loadWorkspace(host, ".", projectRoot, packageCache);
if (packageCache == null) {
return packages;
}
for (let key in packages.keys()) {
let config = packages[key];
if (config.root.startsWith(`${packageCache}/`) && !(await exists(config.root))) {
throw new Error(`${key} is not in the package cache (${config.root}). Run 'zena pkg fetch'.`);
}
}
return packages;
}
// `loadPackages`, or null after printing why the workspace did not load.
// A manifest that cannot be read is a fault in the input, like a syntax
// error, and its message names the manifest. Thrown, it escaped
// `compileFile` before any of its handlers, so `zc` trapped with no
// message at all (https://github.com/elematic/zena/issues/534).
async function loadPackagesOrReport(
host: CompilerHost,
projectRoot: String | null,
packageCache: String | null
): Future<HashMap<String, PackageConfig> | null> {
try {
return await loadPackages(host, projectRoot, packageCache);
} catch (e) {
console.error(`Error: ${e.message}`);
return null;
}
}
function reportDiagnosticLine(kind: String, file: String, line: i32, column: i32, message: String) {
console.error(`${file}:${i32ToString(line)}:${i32ToString(column)} - ${kind}: ${message}`);
}
/**
* Whether a warning is printed without `ZENA_WARN_UNNECESSARY_CASTS`: one
* about what the program does, where the others are hints about what it
* costs (casts, adaptations, boxing).
*/
function printsByDefault(code: DiagnosticCode) {
return code == DiagnosticCode.DiscardedOwner;
}
/**
* Reports a fault in the `--wit` document with its file, line, column
* and an underline, the way a fault in a `.zena` file is reported, and
* returns whether `e` was one — so a caller can go on to whatever else
* `e` means.
*
* A malformed WIT document is a mistake in the input, so it is a
* diagnostic and a status of 1. The parser signals it by throwing, and
* letting that escape `compileFile` loses the position: `zena`
* printed "the compiler failed on main.zena: expected identifier", and a
* compiler running as a component printed nothing at all. See
* https://github.com/elematic/zena/issues/158.
*/
function reportWitFailure(doc: WitDocument | null, e: Error): boolean {
if (doc == null) {
return false;
}
let text = witDiagnostic(doc as WitDocument, e);
if (text == null) {
return false;
}
console.error(text as String);
return true;
}
/** `text` followed by spaces, up to `width` bytes. */
function padRight(text: String, width: i32) {
let b = new StringBuilder();
b.append(text);
var i = text.length;
while (i < width) {
b.append(" ");
i += 1;
}
return b.toString();
}
/** Spaces followed by `text`, up to `width` bytes. */
function padLeft(text: String, width: i32) {
let b = new StringBuilder();
var i = text.length;
while (i < width) {
b.append(" ");
i += 1;
}
b.append(text);
return b.toString();
}
/** Milliseconds to one decimal place. */
function ms1(value: f64) {
return f64ToString(((value * 10.0) as i64 as f64) / 10.0);
}
/**
* The longest phase name that is a proper prefix of `name` followed by
* `-`, or null. `codegen-discovery-init` nests under
* `codegen-discovery` rather than under `codegen`, so the longest
* match wins.
*/
function parentPhaseOf(name: String, names: GrowableArray<String>) {
var best: String | null = null;
for (let candidate in names) {
if (candidate.length >= name.length) {
continue;
}
if (!name.startsWith(`${candidate}-`)) {
continue;
}
let incumbent = best;
if (incumbent == null || candidate.length > incumbent.length) {
best = candidate;
}
}
return best;
}
/**
* The phase list as JSON, for a caller that is going to do arithmetic
* on it. `ZENA_TIME_JSON=1` with `--time` prints this instead of the
* table; an env var rather than a flag so that neither command line
* has to carry it.
*
* One object per phase, in the order the compiler entered them, each
* with its name, total milliseconds, how many times it was entered,
* and the phase that contains it. Parsing the table instead would mean
* a benchmark breaking whenever a column moved.
*/
function printTimingJson() {
let phases = performance.phases();
let names = new Array<String>(phases.length);
for (let phase in phases) {
names.push(phase.name);
}
let b = new JsonBuilder();
b.beginObject();
b.key("schemaVersion").i32(1);
b.key("phases").beginArray();
for (let phase in phases) {
b.beginObject();
b.key("name").string(phase.name);
b.key("totalMs").f64(phase.total);
b.key("count").i32(phase.count);
b.key("parent");
let parent = parentPhaseOf(phase.name, names);
if (parent != null) { b.string(parent as String); } else { b.nullValue(); }
b.endObject();
}
b.endArray();
b.endObject();
console.log(b.toString());
}
/**
* Prints every phase `performance` measured, in the order the compiler
* first entered each, nested under the phase whose name prefixes it.
* The total is the sum of the top-level phases, which are the ones that
* do not overlap.
*
* The report reads the phase list rather than naming phases itself, so
* a `performance.start` added anywhere in the compiler appears here
* without this function changing.
*/
function printTimingReport() {
let phases = performance.phases();
if (phases.length == 0) {
return;
}
let names = new Array<String>(phases.length);
for (let phase in phases) {
names.push(phase.name);
}
console.log("");
console.log("=== Compiler Timing Report ===");
var total = 0.0;
for (let phase in phases) {
let parent = parentPhaseOf(phase.name, names);
var depth = 0;
var walk = parent;
while (walk != null) {
depth += 1;
walk = parentPhaseOf(walk as String, names);
}
// A top-level phase is one no other phase contains, so these are
// the ones that sum to the whole compile.
let label = if (parent == null) {
total = total + phase.total;
phase.name
} else {
phase.name.sliceBytes((parent as String).length + 1, phase.name.length)
};
let indent = padRight("", depth * 2);
let calls = if (phase.count == 1) { "" } else { ` (${i32ToString(phase.count)} calls)` };
console.log(`${padRight(`${indent}${label}:`, 28)}${padLeft(ms1(phase.total), 9)} ms${calls}`);
}
console.log("------------------------------");
console.log(`${padRight("Total:", 28)}${padLeft(ms1(total), 9)} ms`);
console.log("==============================");
}
/**
* Compiles `options.entry` and writes the module to `options.outPath`.
* Returns 0 on success. On a mistake in the options or an error in the
* program it prints the diagnostics to stderr and returns 1; it never
* ends the process, so a caller can compile again.
*/
/**
* How many compiles a session runs on one compiler before it starts a new
* one. What a compiler accumulates per entry point (nominal types, model
* nodes, instantiations interned on the standard library's own generic
* types) is never released while it lives, so past a couple of dozen
* entries it costs more than sharing the standard library saves. The
* portable execution tests measured the whole saving by eight entries
* and settled on 16; see "Portable Tests" in ../CONTEXT.md.
*/
let entriesPerCompiler = 16;
/**
* Opens a session for compiles with `options`, or prints why it cannot
* and returns null. `entry` and `outPath` are ignored: each compile names
* its own. The workspace's manifests and the WIT-backed packages' source
* are read here, once for every compile the session runs, and `onRead`
* hears about them first.
*/
export async function openCompileSession(options: CompileFileOptions): Future<CompileSession | null> {
// ZENA_CHECK_ALL_BODIES=1 checks every loaded module's bodies when
// its module is checked, instead of leaving a dependency's for
// reachability to ask for. See docs/design/lazy-body-checking.md.
setCheckAllBodies(getEnv("ZENA_CHECK_ALL_BODIES") != null);
// The census's distinct-substitution count keeps a set of keys, so
// it is gathered only when the report is wanted.
setCensusEnabled(getEnv("ZENA_CENSUS") != null);
let {
witPath = "",
worldName = "",
stdlibRoot = "/stdlib",
projectRoot = "",
packageCache = "",
testMode = false,
compactImports = false,
warnUnnecessaryCasts = false,
} = options;
// Read with `??` rather than a destructuring default: a default in a
// destructuring pattern does not see module-level bindings, and these
// name theirs rather than writing it out.
let target = options.target ?? defaultTarget;
let onRead = options.onRead ?? ignoreRead;
if (!isKnownTarget(target)) {
console.error("Error: invalid target '" + target + "' (expected " +
knownTargetsDescription() + ")");
return null;
}
// A declared world (docs/design/component-emission.md, Part 3): the
// WIT becomes the authority the program is compiled against, and
// disagreements between it and the Zena are errors.
if ((witPath != "" || worldName != "") && !targetEmitsComponent(target)) {
console.error(
"Error: --wit/--world declare a component's world, and the " +
"target is '" + target + "'. Use --target component or --target zena-component.");
return null;
}
if (worldName != "" && witPath == "") {
console.error("Error: --world names a world in a --wit document, " +
"and no --wit was given.");
return null;
}
let extensionWits = new Array<String>();
if (let {extensionWitPaths} = options) {
for (let path in extensionWitPaths) {
extensionWits.push(path);
}
}
if (extensionWits.length > 0 && (witPath == "" || worldName == "")) {
console.error("Error: --extension-wit checks the program's world against " +
"its extensions' WIT, and no --wit and --world name that world.");
return null;
}
if (let {importedStringConstants as given} = options) {
if (given == "") {
console.error("Error: --imported-string-constants names a module, " +
"and the name is empty.");
return null;
}
if (!targetUsesJsStrings(target)) {
console.error(
"Error: --imported-string-constants names the module string " +
"literals are imported from, and the target is '" + target +
"', which imports none. Use --target js or --target zena-js.");
return null;
}
}
if (compactImports && targetEmitsComponent(target)) {
console.error("Error: --compact-imports writes a core module's imports " +
`in an encoding wasmtime does not read, and the target is '${target}', ` +
"which emits a component.");
return null;
}
let host = new FileHost(testMode, stdlibRoot, onRead);
// The declared world's WIT: one file, or a directory whose *.wit
// files are concatenated in name order into one document.
var witSource = "";
// Kept so a failure anywhere in the compile can be pinned to the file
// and line it came from; the parser only knows offsets into the
// joined document.
var witDoc: WitDocument | null = null;
if (witPath != "") {
if (!(await exists(witPath))) {
console.error("Error: --wit path does not exist: " + witPath);
return null;
}
let doc = await readWitDocument(host, witPath);
witDoc = doc;
witSource = doc.source;
}
// The program's views of its extensions' interfaces, against the
// extensions' own WIT: a problem is reported here, naming the
// interface, before the program is checked against the world.
if (extensionWits.length > 0) {
var hostAst: WitAst | null = null;
try {
hostAst = parseSyntax(witSource);
} catch (e) {
if (e is Error && reportWitFailure(witDoc, e)) {
return null;
}
throw e;
}
var problems = 0;
for (let path in extensionWits) {
if (!(await exists(path))) {
console.error("Error: --extension-wit path does not exist: " + path);
return null;
}
let guestDoc = await readWitDocument(host, path);
var guestAst: WitAst | null = null;
try {
guestAst = parseSyntax(guestDoc.source);
} catch (e) {
if (e is Error) {
let where = witDiagnostic(guestDoc, e) ?? e.message;
console.error(`Error: ${where}`);
return null;
}
throw e;
}
for (let problem in checkExtensionViews(hostAst as WitAst, worldName,
guestAst as WitAst, path)) {
console.error(`Error: ${problem}`);
problems += 1;
}
}
if (problems > 0) {
return null;
}
}
let loaded = await loadPackagesOrReport(host, if (projectRoot == "") null else projectRoot,
if (packageCache == "") null else packageCache);
if (loaded == null) {
return null;
}
let packages = loaded as HashMap<String, PackageConfig>;
// A declared world's document answers for its own packages: the
// program imports the world's interfaces by name (`test:app/oracle`
// for a document declaring `package test:app`), and the resolver
// maps the namespace to a WIT-backed package rooted at the document.
// A namespace the manifest or the stdlib already provides keeps its
// package — a document vendoring `wasi:clocks` does not take over
// `wasi` — and its interfaces are reached as before.
if (witSource != "") {
// The first thing that parses the document, so a malformed one is
// reported here rather than from deeper in the compile.
try {
for (let namespace in declaredPackageNamespaces(witSource)) {
if (namespace == "wasi" || namespace == "zena" || packages.has(namespace)) { continue; }
let declared = new PackageConfig("", null);
declared.witRoot = witPath;
packages[namespace] = declared;
}
} catch (e) {
if (e is Error && reportWitFailure(witDoc, e)) {
return null;
}
throw e;
}
}
// The WIT-backed packages' real source, so the encoder emits their
// interfaces' true types rather than deriving them from the
// synthesized declarations (which are flattened core shapes), and so
// a declared world can import their interfaces by name. Name-sorted:
// a HashMap iterates in uid order, which depends on what the process
// did earlier, and emitted bytes must not.
var packagesWit = "";
if (targetEmitsComponent(target)) {
// Including the packages the stdlib carries (`wasi` and `zena:host`),
// the same set the resolver sees.
let allPackages = withBuiltinPackages(stdlibRoot, packages);
allPackages["zena"] = buildStdlibConfig(stdlibRoot);
let witPackages = new Array<String>();
let packageNames = allPackages.keys();
for (let packageName in packageNames) {
let root = allPackages[packageName].witRoot;
// The declared document is the world's own source, parsed
// alongside these; it does not ride along a second time.
if (root != null && (root as String) != witPath) {
witPackages.push(packageName);
}
}
let byteLess = (x: String, y: String) => {
var minLen = x.length;
if (y.length < minLen) { minLen = y.length; }
for (var i = 0; i < minLen; i += 1) {
let d = x.getByteAt(i) - y.getByteAt(i);
if (d != 0) { return d < 0; }
}
return x.length < y.length;
};
for (var a = 0; a < witPackages.length; a += 1) {
for (var b = a + 1; b < witPackages.length; b += 1) {
if (byteLess(witPackages[b], witPackages[a])) {
let t = witPackages[a];
witPackages[a] = witPackages[b];
witPackages[b] = t;
}
}
}
for (let packageName in witPackages) {
packagesWit = packagesWit +
(await readWitSource(host, allPackages[packageName].witRoot as String)) + "\n";
}
host.packagesWit = packagesWit;
}
return new CompileSession(
options, host, {stdlibRoot, packages, warnUnnecessaryCasts}, witSource, witDoc);
}
/**
* Compiles entry points one after another on one compiler, so what they
* share, the standard library and the packages they import, is loaded,
* parsed and checked once: each compile carries the previous one's check
* forward for every file whose source has not changed. What every compile
* needs is read once, by `openCompileSession`; the runtime memory module a
* component embeds is built by the first compile that needs it.
*
* Every option but `entry` and `outPath` belongs to the session, and
* `compile` takes those two. `compileFile` is a session of one compile.
*/
export final class CompileSession {
#options: CompileFileOptions;
#host: FileHost;
#compilerOptions: CompilerOptions;
var #compiler: Compiler;
#witSource: String;
#witDoc: WitDocument | null;
var #previous: ProgramCheckResult | null = null;
var #compiles = 0;
var #runtimeMemory: ByteBuffer | null = null;
var #sources = new GrowableArray<String>();
new(
options: CompileFileOptions,
host: FileHost,
compilerOptions: CompilerOptions,
witSource: String,
witDoc: WitDocument | null
) : #options = options,
#host = host,
#compilerOptions = compilerOptions,
#compiler = createCompiler(host, compilerOptions),
#witSource = witSource,
#witDoc = witDoc;
/**
* The files the last compile's program is made of, as `onRead` names
* them: its entry and everything that reaches, the standard library
* included, whether this compile read them or an earlier one did.
* WIT-backed modules have no file; their WIT is read when the session
* opens. Empty when the last compile failed before it had a program.
*/
sources: GrowableArray<String> {
get { return this.#sources; }
}
/** The runtime memory module, built or read on first use. */
async #runtimeMemoryModule(compiler: Compiler, stdlibRoot: String, runtimeMemoryPath: String): Future<ByteBuffer> {
let built = this.#runtimeMemory;
if (built != null) {
return built as ByteBuffer;
}
let module = if (runtimeMemoryPath == "") {
await compileComponentRuntimeModule(compiler, stdlibRoot)
} else {
// Already built, by a driver that keeps them between builds.
new ByteBuffer().writeBytes((await readFileBytes(runtimeMemoryPath)) as ByteArray)
};
this.#runtimeMemory = module;
return module;
}
/**
* Compiles `entry`, a source file relative to the working directory,
* and writes its module to `outPath`. Returns 0, or 1 after printing the
* diagnostics.
*/
async compile(entry: String, outPath: String): Future<i32> {
let options = this.#options;
let {
stdlibRoot = "/stdlib",
testMode = false,
time = false,
debugNames = false,
compactImports = false,
warnUnnecessaryCasts = false,
progress = false,
witPath = "",
worldName = "",
} = options;
let target = options.target ?? defaultTarget;
let runtimeMemoryPath = options.runtimeMemoryPath ?? "";
let optLevel = options.optLevel ?? defaultOptLevel;
let importedStringConstants =
options.importedStringConstants ?? defaultImportedStringConstants;
let filename = entry;
let witSource = this.#witSource;
let witDoc = this.#witDoc;
if (this.#compiles == entriesPerCompiler) {
// Nothing to release selectively: the instantiations a compile
// adds are interned on the standard library's own types, so the
// shared part is what grows. Replacing the compiler is the disposal.
this.#compiler = createCompiler(this.#host, this.#compilerOptions);
this.#previous = null;
this.#compiles = 0;
}
this.#compiles += 1;
this.#sources = new GrowableArray<String>();
let compiler = this.#compiler;
let host = this.#host;
host.entryPath = filename;
if (testMode) {
// Test mode gives the entry a `main`, so its source as an entry
// differs from its source as another file's import. Dropping it from
// the compiler's cache before and after keeps either version from
// serving a compile it does not belong to.
compiler.delete(filename);
}
// Against a declared world the entry wrapper also implements the
// world's async exports, which takes the WIT the compiler itself does
// not link. Without a declared world the compiler writes its own.
let declaredWit = witSource;
let declaredWorld = worldName;
let declaredPackages = host.packagesWit;
let compileOptions: CompileOptions = if (witSource == "") {
{entry: filename, target}
} else {
{
entry: filename,
target,
componentWrapperSynth:
(entryPath: String, ast: Module) =>
synthesizeExportWrapper(declaredWit, declaredWorld, entryPath,
ast, declaredPackages),
}
};
if (progress) {
console.log(`Compiling ${filename}...`);
}
try {
let compResult = await compiler.compile(compileOptions);
let sources = new GrowableArray<String>();
for (let file in compResult.files) {
if (!isWitModulePath(file.path)) {
sources.push(host.fileOf(file.path));
}
}
this.#sources = sources;
let checkResults = checkCompilation(compResult, this.#previous);
this.#previous = checkResults;
let {diagnostics} = checkResults;
var hasError = false;
for (let diag in diagnostics) {
if (diag.severity == DiagnosticSeverity.Error) {
if (diag.location != null) {
let loc = diag.location as SourceSpan;
reportDiagnosticLine("Error", loc.file, loc.line, loc.column, diag.message);
} else {
console.error("Error: " + diag.message);
}
hasError = true;
} else if (diag.severity == DiagnosticSeverity.Warning &&
(warnUnnecessaryCasts || printsByDefault(diag.code))) {
if (diag.location != null) {
let loc = diag.location as SourceSpan;
reportDiagnosticLine("Warning", loc.file, loc.line, loc.column, diag.message);
} else {
console.error("Warning: " + diag.message);
}
}
}
if (hasError) {
return 1;
}
checkResults.results[filename].model;
let entryAst = compResult.entry.ast;
let units = new Array<CompilationUnit>();
var entryUnit: CompilationUnit | null = null;
for (let file in compResult.files) {
let res = checkResults.results[file.path];
if (res != null) {
let unit = {ast: file.ast, model: res.model};
units.push(unit);
if (file.ast.path == entryAst.path) {
entryUnit = unit;
}
}
}
markTypes("check");
let tCodegen = performance.start("codegen");
let program = new Program(units, entryUnit);
// Every compile goes AST -> ZIR -> wasm; a lowering bail is a
// fatal error. ZENA_ZIR_STATS=1 prints the lowered count.
let zirStats = getEnv("ZENA_ZIR_STATS") != null;
// ZENA_WIDE_ARITHMETIC=1 emits the wide-arithmetic proposal's
// instructions instead of the sequences that mean the same thing.
// Opt-in because V8 does not implement the proposal yet.
let wideArithmetic = getEnv("ZENA_WIDE_ARITHMETIC") != null;
// Template lowering (docs/design/template-zir.md) is on unless
// ZENA_TEMPLATES=0; ZENA_TEMPLATE_CHECK=1 lowers every templated
// body directly too and fails on any difference.
let templatesEnv = getEnv("ZENA_TEMPLATES");
let templates = templatesEnv == null || templatesEnv as String != "0";
let templateCheck = getEnv("ZENA_TEMPLATE_CHECK") != null;
// `-o out.wat` emits the WAT text directly — the readable form of
// exactly what the binary build would contain, for inspecting a
// program's emitted shape (`zena build hello.zena -o hello.wat`).
// `debug` contract clauses are compiled for a test build and for a
// debug build (`-g`), and left out of every other
// (docs/design/contracts.md).
let debugContracts = testMode || debugNames;
if (outPath.endsWith(".wat")) {
let watOnly = new WatGenerator(target, zirStats, optLevel);
watOnly.wideArithmetic = wideArithmetic;
watOnly.debugContracts = debugContracts;
watOnly.importedStringConstants = importedStringConstants;
watOnly.compactImports = compactImports;
watOnly.templates = templates;
watOnly.templateCheck = templateCheck;
watOnly.interner = checkResults.sharedState.interner;
await writeFile(outPath, watOnly.generate(program));
performance.end(tCodegen);
if (progress) {
console.log("Success: wrote " + outPath);
}
return 0;
}
let generator = new BinaryGenerator(target, zirStats, debugNames, optLevel);
generator.wideArithmetic = wideArithmetic;
generator.debugContracts = debugContracts;
generator.importedStringConstants = importedStringConstants;
generator.compactImports = compactImports;
generator.templates = templates;
generator.templateCheck = templateCheck;
generator.propagate = getEnv("ZENA_PROPAGATE") != "0";
// Codegen builds its unions through the checker's interner, so a
// union means one object across the whole compile.
generator.interner = checkResults.sharedState.interner;
if (targetEmitsComponent(target)) {
// The component's second core module, owning linear memory and
// the allocator. Compiled up front — whether the program needs it
// is only known after its own compile, and this one is small.
//
// The module emits few bytes and still costs a whole compile, with
// its own load, parse, scope and check of the standard library it
// draws on, which land in the same phase totals as the program's
// own. Timed separately so the report says how much of a component
// build is this module.
let tRuntimeModule = nowMs();
// Suspended: this is a compile of its own, and its load, parse,
// scope and check would otherwise be added to this program's,
// which made the report's total exceed wall-clock time by the
// whole nested compile.
performance.suspend();
generator.runtimeMemoryModule =
await this.#runtimeMemoryModule(compiler, stdlibRoot, runtimeMemoryPath);
performance.resume();
performance.add("codegen-runtime-module", nowMs() - tRuntimeModule);
// A declared world compiles against its own document, with the
// WIT-backed packages spliced in so it can import their
// interfaces by name; without one, each interface's WIT is
// derived from the program, except for the packages' own.
generator.importEncoder = if (witPath != "") {
makeImportEncoder(witSource, worldName, host.packagesWit)
} else {
makeImportEncoder(null, "", host.packagesWit)
};
}
let wasmBytes = generator.generate(program).toByteArray();
markTypes("emit");
await writeFileBytes(outPath, wasmBytes as FixedArray<u8>);
// The WAT dump runs a SECOND full generator pass and its text
// dwarfs the binary (~30x — the tests module's dump is ~135 MB),
// so it is opt-in for debugging.
if (getEnv("ZENA_EMIT_WAT") != null) {
let watGenerator = new WatGenerator(target, false, optLevel);
watGenerator.debugContracts = debugContracts;
watGenerator.importedStringConstants = importedStringConstants;
watGenerator.compactImports = compactImports;
let watString = watGenerator.generate(program);
await writeFile(outPath + ".wat", watString);
}
performance.end(tCodegen);
if (progress) {
console.log("Success: wrote " + outPath);
}
// ZENA_CENSUS=1 prints what the compile retained, by object kind
// (census.zena). After codegen, so the type-key counters have
// everything the generator interned.
if (getEnv("ZENA_CENSUS") != null) {
reportCensus(program);
}
if (time) {
if (getEnv("ZENA_TIME_JSON") != null) {
printTimingJson();
} else {
printTimingReport();
}
}
} catch (e) {
// A syntax error is a fault in the input, and the parser has already
// formatted it with its file, line, column and an underline. Report
// it the way a type error is reported and fail: the banner and the
// wasm backtrace below are for a fault in the compiler itself, and
// printing them here says the wrong thing about whose bug it is.
if (e is SyntaxError) {
console.error(e.message);
return 1;
}
// The same for a fault in the declared world's WIT, which the
// encoder and the wrapper synthesizer reach only here.
if (e is Error && reportWitFailure(witDoc, e)) {
return 1;
}
console.log("Exception caught in CLI compiler!");
if (e is Error) {
console.log("Error message: " + e.message);
let stack = e.getStackTrace();
if (stack != null) {
console.log("Stack Trace: \n" + stack);
}
}
throw e;
} finally {
if (testMode) {
compiler.delete(filename);
}
}
return 0;
}
}
export async function compileFile(options: CompileFileOptions): Future<i32> {
let session = await openCompileSession(options);
if (session == null) {
return 1;
}
return await session.compile(options.entry, options.outPath);
}
- 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 |
|
|