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

9.4 KiB Raw
{
  "name": "zena-lang:compiler",
  "did": "did:plc:lbwd3sdsokoh3f75i37e44o2",
  "version": "0.0.2-preview.1",
  "description": "The Zena self-hosted compiler",
  "license": "MIT",
  "source": "src/lib",
  "files": [
    "src/lib"
  ],
  "main": "compiler",
  "exports": {
    "analysis/purity": {},
    "ast": {},
    "ast-json": {},
    "census": {},
    "checker": {},
    "code-template": {},
    "codegen/binary-generator": {},
    "codegen/component-emitter": {},
    "codegen/component-runtime": {},
    "codegen/wat-generator": {},
    "comment-attachment": {},
    "compile-file": {},
    "compiler": {},
    "compiler-options": {},
    "compiler-target": {},
    "component-entry": {},
    "diagnostics": {},
    "doc-comment": {},
    "extension-views": {},
    "fs-host": {},
    "intrinsics": {},
    "library-loader": {},
    "line-index": {},
    "module-resolver": {},
    "node-map": {},
    "package-manifest": {},
    "parser": {},
    "prelude": {},
    "program": {},
    "scope": {},
    "scope/scope": {},
    "scope/symbol": {},
    "semantic-model": {},
    "simd": {},
    "stdlib-manifest": {},
    "targets": {},
    "time": {},
    "tokenizer": {},
    "types": {},
    "visitor": {},
    "well-known": {},
    "wit-module-synth": {},
    "wit-source": {}
  },
  "dependencies": {
    "zena-lang:wit-parser": {
      "path": "../wit-parser",
      "version": "~0.0.1-preview.1"
    }
  },
  "locks": [
    "zena-lock.json",
    "package-lock.json"
  ],
  "scripts": {
    "build": {
      "dependencies": [
        "build:cli",
        "build:tests"
      ]
    },
    "build:scripts": {
      "command": "tsc",
      "files": [
        "src-ts/**/*.ts",
        "tsconfig.json"
      ],
      "output": [
        "scripts/**/*.js",
        "scripts/**/*.js.map"
      ],
      "clean": "if-file-deleted",
      "dependencies": [
        "../runtime-js:build"
      ]
    },
    "build:cli": {
      "#command": "The checked-in CLI module bootstrap compiles the compiler, run through zena's binary with ZENA_CLI_MODULE pointing at packages/cli/bootstrap/zena.wasm so this step waits only on cargo and never on packages/cli/out/zena.wasm, which this compiler builds. ZENA_OPT_LEVEL=2 (the env form, which a bootstrap that predates the -O flag ignores rather than misreads) makes the working compiler an -O2 build: it compiles the zena module in 20s where the -O1 build takes 27s, and every build and test step downstream of this one runs it (docs/design/compiler-memory.md).",
      "command": "mkdir -p out && ZENA_GC_RESERVE_MB=1536 ZENA_OPT_LEVEL=2 ZENA_CLI_MODULE=../cli/bootstrap/zena.wasm ../../target/release/zena build src/cli/main.zena -o out/cli.wasm",
      "files": [
        "src/cli/**/*.zena",
        "../cli/bootstrap/zena.wasm"
      ],
      "output": [
        "out/cli.wasm"
      ],
      "dependencies": [
        "source",
        "../stdlib:lib",
        "../cli:build:binary"
      ]
    },
    "build:tests": {
      "#dependencies": "precompile:cli, not build:self-hosted: this program is built by stage A (see build-wasi-tests.ts), and precompiling it is what keeps running it off Cranelift. Depending on stage B put the four suites behind its 64s.",
      "command": "node scripts/build-wasi-tests.js",
      "files": [
        "src/test/**/*.zena",
        "!src/test/__all_tests__.zena",
        "out/cli.wasm"
      ],
      "output": [
        "out/test-self/__all_tests__.wasm",
        "src/test/__all_tests__.zena"
      ],
      "dependencies": [
        "source",
        "../stdlib:lib",
        "build:scripts",
        {
          "script": "precompile:cli",
          "cascade": false
        },
        "../cli:build"
      ]
    },
    "build:self-hosted": {
      "command": "ZENA_GC_RESERVE_MB=1536 ZENA_TEMPLATE_CHECK=1 ZENA_COMPILER_WASM=out/cli.wasm ../../target/release/zena -g -O2 build src/cli/main.zena -o out/cli-self.wasm",
      "files": [
        "src/cli/**/*.zena",
        "out/cli.wasm"
      ],
      "output": [
        "out/cli-self.wasm"
      ],
      "dependencies": [
        "source",
        "../stdlib:lib",
        {
          "script": "precompile:cli",
          "cascade": false
        },
        "../cli:build"
      ]
    },
    "test": {
      "#": "Everything, which is what CI runs. `test:smoke` is this minus the fixpoint check, so the two cannot drift.",
      "dependencies": [
        "test:smoke",
        "test:fixpoint"
      ]
    },
    "test:unit": {
      "command": "node scripts/run-wasmtime.js unit",
      "files": [
        "scripts/run-wasmtime.js",
        "out/test-self/__all_tests__.wasm",
        "src/cli/**/*.zena",
        "test-files/snapshots/**/*.snap",
        "test-files/**/*.zena"
      ],
      "dependencies": [
        "source",
        "../stdlib:lib",
        "build:scripts",
        {
          "script": "build:tests",
          "cascade": false
        },
        "../cli:build"
      ]
    },
    "test:syntax": {
      "command": "node scripts/run-wasmtime.js syntax",
      "files": [
        "../../tests/language/syntax/**/*.zena",
        "../../tests/language/syntax/**/*.ast.json",
        "scripts/run-wasmtime.js",
        "out/test-self/__all_tests__.wasm"
      ],
      "dependencies": [
        "../stdlib:lib",
        "build:scripts",
        {
          "script": "build:tests",
          "cascade": false
        },
        "../cli:build"
      ]
    },
    "test:semantics": {
      "command": "node scripts/run-wasmtime.js semantics",
      "files": [
        "../../tests/language/semantics/**/*.zena",
        "scripts/run-wasmtime.js",
        "out/test-self/__all_tests__.wasm",
        "../../zena-package.json"
      ],
      "dependencies": [
        "../stdlib:lib",
        "build:scripts",
        {
          "script": "build:tests",
          "cascade": false
        },
        "../cli:build"
      ]
    },
    "test:execution": {
      "command": "node scripts/run-wasmtime.js execution",
      "files": [
        "../../tests/language/execution/**/*.zena",
        "scripts/run-wasmtime.js",
        "out/test-self/__all_tests__.wasm",
        "../../zena-package.json"
      ],
      "env": {
        "ZENA_TEST_OPT_LEVEL": {
          "external": true
        },
        "ZENA_PROPAGATE": {
          "external": true
        }
      },
      "dependencies": [
        "../stdlib:lib",
        "build:scripts",
        {
          "script": "build:tests",
          "cascade": false
        },
        "../cli:build"
      ]
    },
    "test:execution:o2": {
      "#": "The execution suite compiled at -O2, through the module loop the default level skips. It writes to out/test-exec-O2, and runs after test:execution rather than beside it, which keeps CI's peak memory where it was.",
      "command": "node scripts/run-wasmtime.js execution",
      "files": [
        "../../tests/language/execution/**/*.zena",
        "scripts/run-wasmtime.js",
        "out/test-self/__all_tests__.wasm",
        "../../zena-package.json"
      ],
      "env": {
        "ZENA_TEST_OPT_LEVEL": "2",
        "ZENA_PROPAGATE": {
          "external": true
        }
      },
      "dependencies": [
        "../stdlib:lib",
        "build:scripts",
        {
          "script": "build:tests",
          "cascade": false
        },
        "../cli:build",
        "test:execution"
      ]
    },
    "test:interop": {
      "command": "node scripts/external-functions-test.js",
      "files": [
        "scripts/external-functions-test.js",
        "out/cli.wasm"
      ],
      "dependencies": [
        "build:scripts",
        "../cli:build",
        "../runtime-js:build",
        {
          "script": "precompile:cli",
          "cascade": false
        },
        "../stdlib:lib"
      ]
    },
    "test:fixpoint": {
      "#dependencies": "test:execution:o2 without its fingerprint, so the 4.7 GiB stage-C compile never runs beside the 6.5 GiB execution suite and cli:test:zena on CI's 16 GiB runner.",
      "command": "node scripts/check-fixpoint.js",
      "files": [
        "src/cli/**/*.zena",
        "out/cli-self.wasm",
        "scripts/check-fixpoint.js"
      ],
      "output": [
        "out/cli-self2.wasm"
      ],
      "dependencies": [
        "source",
        "../stdlib:lib",
        "build:scripts",
        {
          "script": "build:self-hosted",
          "cascade": false
        },
        {
          "script": "test:execution:o2",
          "cascade": false
        },
        "../cli:build"
      ]
    },
    "test:component": {
      "command": "node scripts/component-e2e.js",
      "files": [
        "scripts/component-e2e.js",
        "test-files/component/**/*.zena",
        "test-files/component/**/*.wit",
        "out/cli.wasm"
      ],
      "output": [
        "out/component/**/*.wasm"
      ],
      "dependencies": [
        "build:scripts",
        {
          "script": "precompile:cli",
          "cascade": false
        },
        "../cli:build",
        "../stdlib:lib"
      ]
    },
    "test:smoke": {
      "#": "Every compiler test but the fixpoint check. See the root package's test:smoke for when to reach for it.",
      "dependencies": [
        "test:unit",
        "test:component",
        "test:syntax",
        "test:semantics",
        "test:execution",
        "test:execution:o2",
        "test:interop"
      ]
    },
    "precompile:cli": {
      "#": "Stage A's .cwasm, untracked so remote caches never save machine code built for one host CPU and restore it onto another.",
      "command": "../../target/release/zena precompile out/cli.wasm",
      "dependencies": [
        "build:cli",
        "../cli:build"
      ]
    }
  }
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19