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

10.0 KiB Raw
/**
 * Textual ZIR printer, for tests and debugging.
 *
 * Format (golden-tested in test/ir_test.zena — change deliberately):
 *
 *   fn @name {
 *     b0(%0: i32, %1: i32):
 *       %2 = i32.add %0, %1
 *       ret %2
 *   }
 */
import { StringBuilder } from 'zena:core';
import { ValType, ValTypeVoid, ValTypeFunc, ValTypeI32, ValTypeI64, ValTypeF32, ValTypeF64, ValTypeV128, ValTypeFuncRef, ValTypeExternRef, ValTypeRefExtern, ValTypeAnyRef, ValTypeEqRef, ValTypeStructRef, ValTypeNullRef, ValTypeOptRef, ValTypeRef, ValTypeRefNull, ValTypeI8, ValTypeI16 } from '../wasm.zena';
import { WasmType } from '../wasm.zena';
import { WasmStruct } from '../wasm-module.zena';
import { IrBody, IrOp, IrRef, IrRefFunc, IrRefGlobal, IrRefTag, IrRefType, IrRefField, IrRefClassInterface, IrRefStringLit, irOpName, isSimdOp, simdExtraOperandCount } from './ir.zena';
import { simdName } from '../../simd.zena';

function typeName(t: ValType) {
  return match (t) {
    case ValTypeVoid: 'void'
    case ValTypeFunc: 'func'
    case ValTypeI32: 'i32'
    case ValTypeI64: 'i64'
    case ValTypeF32: 'f32'
    case ValTypeF64: 'f64'
    case ValTypeV128: 'v128'
    case ValTypeFuncRef: 'funcref'
    case ValTypeExternRef: 'externref'
    case ValTypeRefExtern: '(ref extern)'
    case ValTypeAnyRef: 'anyref'
    case ValTypeEqRef: 'eqref'
    case ValTypeStructRef: 'structref'
    case ValTypeNullRef: 'nullref'
    case ValTypeOptRef: 'optref'
    case ValTypeRef as r: `(ref ${wasmTypeName(r.target)})`
    case ValTypeRefNull as r: `(ref null ${wasmTypeName(r.target)})`
    case ValTypeI8: 'i8'
    case ValTypeI16: 'i16'
  };
}

function wasmTypeName(t: WasmType): String {
  if (t is WasmStruct) {
    return nameOrQuestion(t.name);
  }
  return '?';
}

function nameOrQuestion(name: String | null): String {
  if (name == null) {
    return '?';
  }
  return name;
}

function refName(r: IrRef) {
  return match (r) {
    case IrRefFunc as f: '@' + nameOrQuestion(f.target.name)
    case IrRefGlobal as g: '$' + g.target.name
    case IrRefTag as t: 'tag#' + i32ToString(t.target.index)
    case IrRefType as t: wasmTypeName(t.target)
    case IrRefField as f: `${nameOrQuestion(f.owner.name)}.${f.fieldName}`
    case IrRefClassInterface as ci: `${nameOrQuestion(ci.classStruct.name)}/${nameOrQuestion(ci.ifaceStruct.name)}`
    case IrRefStringLit as s: `"${s.value}"`
  };
}

export final class IrPrinter {
  body: IrBody;
  sb = new StringBuilder();
  new(this.body);

  print(name: String): String {
    this.sb.append('fn @').append(name).append(' {\n');
    var blockId = 0;
    while (blockId < this.body.blocks.length) {
      this.#printBlock(blockId);
      blockId += 1;
    }
    this.sb.append('}\n');
    return this.sb.toString();
  }

  #printBlock(blockId: i32): void {
    let blk = this.body.blocks[blockId];
    this.sb.append('  b').append(i32ToString(blockId)).append('(');
    var i = 0;
    while (i < blk.params.length) {
      if (i > 0) {
        this.sb.append(', ');
      }
      let p = blk.params[i];
      this.sb.append('%').append(i32ToString(p)).append(': ');
      let t = this.body.resultType(p);
      if (t == null) {
        this.sb.append('?');
      } else {
        this.sb.append(typeName(t));
      }
      i += 1;
    }
    this.sb.append('):\n');
    for (let inst in blk.insts) {
      this.#printInst(inst);
    }
  }

  #printInst(inst: i32): void {
    this.sb.append('    ');
    if (this.body.producesValue(inst)) {
      this.sb.append('%').append(i32ToString(inst)).append(' = ');
    }
    let op = this.body.op(inst);
    this.sb.append(irOpName(op));
    this.#printOperands(inst, op);
    this.sb.append('\n');
  }

  #printOperands(inst: i32, op: IrOp): void {
    let {body} = this;
    let av = body.a[inst];
    let bv = body.b[inst];
    if (op == IrOp.nop || op == IrOp.unreachable) {
      return;
    }
    if (op == IrOp.const_i32) {
      this.sb.append(' ').append(i32ToString(av));
      return;
    }
    if (op == IrOp.const_i64) {
      this.sb.append(' ').append(i64ToString(body.constI64[av]));
      return;
    }
    if (op == IrOp.const_f32 || op == IrOp.const_f64) {
      this.sb.append(' ').append(f64ToString(body.constF64[av]));
      return;
    }
    if (op == IrOp.ref_null) {
      return;
    }
    if (op == IrOp.ref_func || op == IrOp.str_lit || op == IrOp.global_get) {
      this.sb.append(' ').append(refName(body.refTable[bv]));
      return;
    }
    if (op == IrOp.global_set) {
      this.#value(av);
      this.sb.append(', ').append(refName(body.refTable[bv]));
      return;
    }
    if (op == IrOp.var_get) {
      this.sb.append(' $v').append(i32ToString(bv));
      return;
    }
    if (op == IrOp.var_set) {
      this.sb.append(' $v').append(i32ToString(bv)).append(', ');
      this.#value(av);
      return;
    }
    if (op == IrOp.ref_test || op == IrOp.ref_cast) {
      this.#value(av);
      this.sb.append(', ').append(typeName(body.typeTable[bv]));
      return;
    }
    if (op == IrOp.struct_get ||
        op == IrOp.iface_pack) {
      this.#value(av);
      this.sb.append(', ').append(refName(body.refTable[bv]));
      return;
    }
    if (op == IrOp.iface_vtable || op == IrOp.iface_instance ||
        op == IrOp.i32_eqz || op == IrOp.i32_wrap_i64 ||
        op == IrOp.i64_extend_i32_s || op == IrOp.f64_convert_i32_s ||
        op == IrOp.ref_is_null || op == IrOp.ref_as_non_null ||
        op == IrOp.array_len) {
      this.#value(av);
      return;
    }
    if (op == IrOp.i32_store || op == IrOp.i32_store8) {
      this.#value(body.extra[av]);
      this.sb.append(',');
      this.#value(body.extra[av + 1]);
      return;
    }
    if (op == IrOp.struct_set) {
      this.#value(body.extra[av]);
      this.sb.append(',');
      this.#value(body.extra[av + 1]);
      this.sb.append(', ').append(refName(body.refTable[bv]));
      return;
    }
    if (op == IrOp.struct_new) {
      this.sb.append(' ').append(refName(body.refTable[bv]));
      this.#argList(av + 1, body.extra[av]);
      return;
    }
    if (op == IrOp.array_new) {
      this.sb.append(' ').append(refName(body.refTable[bv]));
      this.#value(body.extra[av]);
      let init = body.extra[av + 1];
      if (init >= 0) {
        this.sb.append(',');
        this.#value(init);
      }
      return;
    }
    if (op == IrOp.array_set) {
      this.#value(body.extra[av]);
      this.sb.append(',');
      this.#value(body.extra[av + 1]);
      this.sb.append(',');
      this.#value(body.extra[av + 2]);
      return;
    }
    if (op == IrOp.array_copy) {
      for (var i = 0; i < 5; i += 1) {
        if (i > 0) {
          this.sb.append(',');
        }
        this.#value(body.extra[av + i]);
      }
      return;
    }
    if (op == IrOp.call || op == IrOp.ret_call) {
      this.sb.append(' ').append(refName(body.refTable[bv]));
      this.#argList(av + 1, body.extra[av]);
      return;
    }
    if (op == IrOp.call_ref || op == IrOp.ret_call_ref) {
      this.#value(body.extra[av]);
      this.#argList(av + 2, body.extra[av + 1]);
      return;
    }
    if (op == IrOp.throw) {
      this.#argList(av + 1, body.extra[av]);
      return;
    }
    if (op == IrOp.ret) {
      if (av >= 0) {
        this.#value(av);
      }
      return;
    }
    if (op == IrOp.br || op == IrOp.br_if || op == IrOp.br_on_cast ||
        op == IrOp.br_on_cast_fail || op == IrOp.br_table) {
      if (op != IrOp.br) {
        this.#value(av);
      }
      let succs = body.successors(inst);
      var first = op == IrOp.br;
      for (let s in succs) {
        if (!first) {
          this.sb.append(',');
        }
        first = false;
        this.sb.append(' b').append(i32ToString(s.target)).append('(');
        var i = 0;
        while (i < s.argCount) {
          if (i > 0) {
            this.sb.append(', ');
          }
          this.sb.append('%').append(i32ToString(body.extra[s.argStart + i]));
          i += 1;
        }
        this.sb.append(')');
      }
      return;
    }
    if (isSimdOp(op)) {
      this.#printSimdOperands(inst, op);
      return;
    }
    // Binary numeric ops and anything else with two inline value operands.
    this.#value(av);
    this.sb.append(',');
    this.#value(bv);
  }

  /**
   * `simd.binary i32x4.add %3, %4` — the shape came from `irOpName`, so
   * this adds the instruction the opcode immediate names, then the
   * operands, then whatever immediates the shape carries. Without it the
   * fallback would print an opcode number as if it were a value id.
   */
  #printSimdOperands(inst: i32, op: IrOp): void {
    let {body} = this;
    let av = body.a[inst];
    let bv = body.b[inst];
    // The three shapes with no immediates keep their opcode in slot b
    // itself; every other shape puts it first in the slot-b payload.
    let opcodeIsInline = op == IrOp.simd_unary || op == IrOp.simd_binary ||
        op == IrOp.simd_ternary;
    let opcode = if (opcodeIsInline) bv else body.extra[bv];
    this.sb.append(' ').append(simdName(opcode));
    let operands = simdExtraOperandCount(op);
    if (operands > 0) {
      var i = 0;
      while (i < operands) {
        if (i > 0) {
          this.sb.append(',');
        }
        this.#value(body.extra[av + i]);
        i += 1;
      }
    } else if (op != IrOp.simd_const) {
      this.#value(av);
    }
    if (opcodeIsInline) {
      return;
    }
    // The immediates, in the order the slot-b payload holds them after
    // the opcode: an alignment, a lane, or sixteen bytes.
    let count = if (op == IrOp.simd_const || op == IrOp.simd_shuffle) 16
        else if (op == IrOp.simd_load_lane || op == IrOp.simd_store_lane) 2
        else 1;
    var i = 0;
    while (i < count) {
      this.sb.append(' ').append(i32ToString(body.extra[bv + 1 + i]));
      i += 1;
    }
  }

  #value(id: i32): void {
    this.sb.append(' %').append(i32ToString(id));
  }

  #argList(start: i32, count: i32): void {
    this.sb.append('(');
    var i = 0;
    while (i < count) {
      if (i > 0) {
        this.sb.append(', ');
      }
      this.sb.append('%').append(i32ToString(this.body.extra[start + i]));
      i += 1;
    }
    this.sb.append(')');
  }
}

export function printIr(body: IrBody, name: String): String {
  let printer = new IrPrinter(body);
  return printer.print(name);
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19