radiance · Radiance self-hosting compiler

compiler/ radiance/ radiance.rad 42.7 KiB kernel/ lib/ scripts/ seed/ sublime/ test/ vim/ .gitignore 351 B .gitsigners 112 B CONTRIBUTING 2.1 KiB LICENSE 1.1 KiB Makefile 3.8 KiB README 2.5 KiB STYLE 2.5 KiB std.lib 1.4 KiB std.lib.test 380 B
compiler/radiance.rad 42.7 KiB raw
//! Radiance compiler front-end.

/// Binary RIL file output and native loading.
mod binary;
/// Trusted binary image catalogs linked into a native program.
mod images;
use std::mem;
use std::fmt;
use std::io;
use std::lang::alloc;
use std::lang::ast;
use std::lang::parser;
use std::lang::scanner;
use std::lang::resolver;
use std::lang::module;
use std::lang::strings;
use std::lang::package;
use std::lang::il;
use std::lang::lower;
use std::arch::rv64;
use std::arch::rv64::asm;
use std::arch::rv64::printer;
use std::lang::sexpr;
use std::lang::gen::data;
use std::lang::gen::types;
use std::sys;
use std::sys::unix;
use std::collections::dict;

/// Maximum number of modules we can load per package.
constant MAX_LOADED_MODULES: u32 = module::MAX_MODULES;
/// Maximum number of packages we can compile.
constant MAX_PACKAGES: u32 = 4;
/// Total module entries across all packages.
constant MAX_TOTAL_MODULES: u32 = 192;
/// Source code buffer arena (2 MB).
constant MAX_SOURCES_SIZE: u32 = 2097152;
/// Maximum number of test functions we can discover.
constant MAX_TESTS: u32 = 1024;
/// Maximum number of assembly source paths we can load per package.
constant MAX_ASM_MODULES: u32 = 64;
/// Maximum binary image inputs linked into a native catalog.
constant MAX_IMAGES: u32 = 64;

/// AST arena size (32 MB) - retains parsed nodes throughout compilation.
constant TEMP_ARENA_SIZE: u32 = 33554432;
/// Per-function lowering and register-allocation arena size (16 MB).
constant FN_ARENA_SIZE: u32 = 16777216;
/// Main arena size (96 MB) - lives throughout compilation.
/// Used for: resolver data, types, symbols, global IL data, and codegen output.
constant MAIN_ARENA_SIZE: u32 = 100663296;

/// AST storage arena.
static TEMP_ARENA: [u8; TEMP_ARENA_SIZE] = undefined;
/// Scratch storage reclaimed after each generated function.
static FN_ARENA: [u8; FN_ARENA_SIZE] = undefined;
/// Main storage arena - persists throughout compilation.
static MAIN_ARENA: [u8; MAIN_ARENA_SIZE] = undefined;

/// Module source code.
static MODULE_SOURCES: [u8; MAX_SOURCES_SIZE] = undefined;
/// Module entries for all packages.
static MODULE_ENTRIES: [module::ModuleEntry; MAX_TOTAL_MODULES] = undefined;
/// String pool.
static STRING_POOL: strings::Pool = strings::Pool { table: undefined, count: 0 };

/// Package scope.
static RESOLVER_PKG_SCOPE: resolver::Scope = undefined;
/// Errors emitted by resolver.
static RESOLVER_ERRORS: [resolver::Error; resolver::MAX_ERRORS] = undefined;

/// Code generation storage.
static CODEGEN_DATA_SYMS: [data::DataSym; data::MAX_DATA_SYMS] = undefined;
/// Hash table entries for data symbol lookup.
static CODEGEN_DATA_SYM_ENTRIES: [dict::Entry; data::DATA_SYM_TABLE_SIZE] = undefined;

/// Debug info file extension.
constant DEBUG_EXT: *[u8] = ".debug";

/// Maximum rodata size (4MB).
constant MAX_RO_DATA_SIZE: u32 = 4194304;
/// Maximum rwdata size (4MB).
constant MAX_RW_DATA_SIZE: u32 = 4194304;
/// Maximum path length.
constant MAX_PATH_LEN: u32 = 256;
/// Read-only data buffer.
static RO_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = undefined;
/// Read-write data buffer.
static RW_DATA_BUF: [u8; MAX_RW_DATA_SIZE] = undefined;
/// Assembly module source buffer.
static ASM_SOURCE_BUF: [u8; MAX_SOURCES_SIZE] = undefined;
/// Temporary assembly text buffer.
static ASM_TEXT_BUF: [u32; 262144] = undefined;
/// Temporary assembly data buffer.
static ASM_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = undefined;
/// Accumulated assembly read-only data.
static ASM_RO_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = undefined;

/// Assembly source file extension.
constant ASM_SOURCE_EXT: *[u8] = ".ras";
/// Symbol name exported for startup code to call the semantic entry function.
constant DEFAULT_ENTRY_SYMBOL: *[u8] = "::default";

/// Usage string.
constant USAGE: *[u8] =
    "usage: radiance -pkg <name> [-start <input.ras>] -mod <input>.. [-pkg <name> -mod <input>..] -entry <pkg> [-emit ril] [-image <input.ril>] -o <output>\n       radiance -load <input.ril> [-start <input.ras>] [-mod <input.ras>] -o <output>\n       radiance -catalog <output.rad> -image <input.ril>..\n";

/// Compiler error.
union Error: Copy {
    Other,
}

/// What to dump during compilation.
union Dump: Copy {
    /// Don't dump anything.
    None,
    /// Dump the parsed AST before semantic analysis.
    Ast,
    /// Dump the module graph.
    Graph,
    /// Dump the IL.
    Il,
    /// Dump the generated assembly.
    Asm,
}

/// A discovered test function.
record TestDesc: Copy {
    /// Full module qualified path segments (eg. ["std", "tests"]).
    modPath: *[*[u8]],
    /// Test function name (eg. "testFoo").
    fnName: *[u8],
}

/// Source inputs belonging to one command-line package.
record PackageInput: Copy {
    /// Package name from the `-pkg` argument.
    name: *[u8],
    /// Optional startup assembly emitted before generated text.
    startupPath: ?*[u8],
    /// Radiance source paths for this package.
    radPaths: [*[u8]; MAX_LOADED_MODULES],
    /// Number of Radiance source paths.
    radPathCount: u32,
    /// Assembly source paths for this package.
    asmPaths: [*[u8]; MAX_ASM_MODULES],
    /// Number of assembly source paths.
    asmPathCount: u32,
}

/// Compilation context.
record CompileContext: Copy {
    /// Array of packages to compile.
    packages: [package::Package; MAX_PACKAGES],
    /// Driver inputs for each package slot.
    inputs: [PackageInput; MAX_PACKAGES],
    /// Number of packages.
    packageCount: u32,
    /// Index of entry package.
    entryPkgIdx: ?u32,
    /// Global module graph shared by all packages.
    graph: module::ModuleGraph,
    /// Resolver configuration.
    config: resolver::Config,
    /// What to dump during compilation.
    dump: Dump,
    /// Output path for binary.
    outputPath: ?*[u8],
    /// Whether to emit debug info (.debug file).
    debug: bool,
    /// Write binary RIL instead of native instructions.
    emitIl: bool,
    /// Ordered trusted binary image inputs for native linking.
    imagePaths: [*[u8]; MAX_IMAGES],
    /// Number of binary image paths.
    imageCount: u32,
    /// Include zero-initialized storage in the native image's data sections.
    zeroBss: bool,
}

/// Stable driver input storage for the single compilation invocation.
static CONTEXT: CompileContext = undefined;

/// Root module info for a package.
record RootModule: Copy {
    entry: *module::ModuleEntry,
    ast: *mut ast::Node,
}

/// State carried by the streaming lowerer/codegen callback.
record CodegenSinkContext: Copy {
    /// RV64 generator receiving lowered functions.
    generator: *mut rv64::Generator,
    /// Arena holding the current function's lowered IL.
    fnArena: *mut alloc::Arena,
}

/// Accumulated RIL functions and the semantic entry selected during lowering.
record IlSinkContext {
    /// Stable function bodies owned by the lowering arena.
    functions: *mut [*il::Fn],
    /// Function marked with `@default` in the entry package.
    entry: ?*[u8],
    /// Storage for the function list.
    arena: *mut alloc::Arena,
}

/// Entry handling for streamed code generation.
union CodegenEntryMode: Copy {
    /// Do not reserve an entry jump.
    None,
    /// Reserve and patch an entry jump to the `@default` function.
    DefaultEntry,
}

/// Options controlling streamed lowering and code generation.
record CodegenOptions: Copy {
    /// Optional output path used for progress logging.
    logPath: ?*[u8],
    /// Whether to emit debug source locations.
    debug: bool,
    /// How the generated program should handle entry.
    entryMode: CodegenEntryMode,
}

/// Print a driver error line.
fn error(msg: *[*[u8]]) -> Error {
    io::printError("radiance: ");

    for part, i in msg {
        io::printError(part);
        if i < msg.len - 1 {
            io::printError(" ");
        }
    }
    io::printError("\n");
    return Error::Other;
}

/// Print a log line for the given package.
fn pkgLog(pkg: *package::Package, msg: *[*[u8]]) {
    io::printError("radiance: ");
    io::printError(pkg.name);
    io::printError(": ");

    for part, i in msg {
        io::printError(part);
        if i < msg.len - 1 {
            io::printError(" ");
        }
    }
    io::printError("\n");
}

/// Return `true` when `path` ends with `ext`.
fn hasExtension(path: *[u8], ext: *[u8]) -> bool {
    if path.len < ext.len {
        return false;
    }
    let start = path.len - ext.len;
    return mem::eq(&path[start..], ext);
}

/// Create an empty source input set for one package.
fn packageInput(name: *[u8]) -> PackageInput {
    return PackageInput {
        name,
        startupPath: nil,
        radPaths: undefined,
        radPathCount: 0,
        asmPaths: undefined,
        asmPathCount: 0,
    };
}

/// Register, load, and parse `path` within `pkg`.
fn processModule(
    pkg: *mut package::Package,
    graph: *mut module::ModuleGraph,
    path: *[u8],
    nodeArena: *mut ast::NodeArena,
    sourceArena: *mut alloc::Arena
) throws (Error) {
    pkgLog(pkg, &["parsing", "(", path, ")", ".."]);

    let moduleId = try package::registerModule(pkg, graph, path) catch {
        throw error(&["error registering module"]);
    };
    // Read file into remaining arena space.
    let buffer = alloc::remainingBuf(sourceArena);
    if buffer.len == 0 {
        throw error(&["fatal:", "source arena exhausted"]);
    }
    let source = unix::readFile(path, buffer) else {
        throw error(&["error reading file"]);
    };
    if source.len == buffer.len {
        throw error(&["fatal:", "source arena too small, file truncated:", path]);
    }
    // Commit only what was read.
    alloc::commit(sourceArena, source.len);

    let ast = try parser::parse(scanner::SourceLoc::File(path), source, nodeArena, &mut STRING_POOL) catch {
        throw Error::Other;
    };
    try module::setAst(graph, moduleId, ast) catch {
        throw error(&["error setting AST"]);
    };
    try module::setSource(graph, moduleId, source) catch {
        throw error(&["error setting source"]);
    };
}

/// Consume the next argument, or print an error and throw.
fn nextArg(args: *[*[u8]], idx: *mut u32, msg: *[*[u8]]) -> *[u8] throws (Error) {
    set *idx += 1;
    if *idx >= args.len {
        throw error(msg);
    }
    return args[*idx];
}

/// Write a catalog declaration from the ordered binary image inputs.
fn catalogCommand(args: *[*[u8]]) -> i32 {
    if args.len < 4 {
        let _error = error(&["`-catalog` requires an output path and image inputs"]);
        return 1;
    }
    let mut paths: [*[u8]; MAX_IMAGES] = undefined;
    let mut count: u32 = 0;
    let mut index: u32 = 2;
    while index < args.len {
        if not mem::eq(args[index], "-image") or index + 1 >= args.len or count == MAX_IMAGES {
            let _error = error(&["invalid catalog image arguments"]);
            return 1;
        }
        set paths[count] = args[index + 1];
        set count += 1;
        set index += 2;
    }
    try images::catalog(&paths[..count], args[1], &mut STRING_POOL) catch e {
        let _error = error(&[e.message]);
        return 1;
    };
    return 0;
}

/// Parse CLI arguments and initialize the caller's compilation context.
fn processCommand(
    args: *[*[u8]],
    arena: *mut ast::NodeArena,
    ctx: *mut CompileContext
) throws (Error) {
    let mut buildTest = false;
    let mut debugEnabled = false;
    let mut outputPath: ?*[u8] = nil;
    let mut dump = Dump::None;
    let mut entryPkgName: ?*[u8] = nil;
    let mut emitIl = false;
    let mut zeroBss = false;
    let mut imagePaths: [*[u8]; MAX_IMAGES] = undefined;
    let mut imageCount: u32 = 0;

    // Per-package source path tracking.
    let mut inputs: [PackageInput; MAX_PACKAGES] = undefined;
    let mut pkgCount: u32 = 0;
    let mut currentPkgIdx: ?u32 = nil;

    if args.len == 0 {
        io::printError(USAGE);
        throw Error::Other;
    }
    let mut idx: u32 = 0;

    while idx < args.len {
        let arg = args[idx];
        if mem::eq(arg, "-pkg") {
            try nextArg(args, &mut idx, &["`-pkg` requires a package name"]);
            if pkgCount >= MAX_PACKAGES {
                throw error(&["too many packages specified"]);
            }
            set inputs[pkgCount] = packageInput(args[idx]);
            set currentPkgIdx = pkgCount;
            set pkgCount += 1;
        } else if mem::eq(arg, "-mod") {
            try nextArg(args, &mut idx, &["`-mod` requires a module path"]);
            let pkgIdx = currentPkgIdx else {
                throw error(&["`-mod` must follow a `-pkg` argument"]);
            };
            let input = &mut inputs[pkgIdx];
            if hasExtension(args[idx], ASM_SOURCE_EXT) {
                if input.asmPathCount >= MAX_ASM_MODULES {
                    throw error(&["too many assembly modules specified"]);
                }
                set input.asmPaths[input.asmPathCount] = args[idx];
                set input.asmPathCount += 1;
            } else {
                if input.radPathCount >= MAX_LOADED_MODULES {
                    throw error(&["too many modules specified for package"]);
                }
                set input.radPaths[input.radPathCount] = args[idx];
                set input.radPathCount += 1;
            }
        } else if mem::eq(arg, "-start") {
            try nextArg(args, &mut idx, &["`-start` requires an assembly path"]);
            let pkgIdx = currentPkgIdx else {
                throw error(&["`-start` must follow a `-pkg` argument"]);
            };
            let input = &mut inputs[pkgIdx];
            if input.startupPath <> nil {
                throw error(&["package", input.name, "has more than one startup file"]);
            }
            if not hasExtension(args[idx], ASM_SOURCE_EXT) {
                throw error(&["`-start` requires a `.ras` assembly file"]);
            }
            set input.startupPath = args[idx];
        } else if mem::eq(arg, "-entry") {
            try nextArg(args, &mut idx, &["`-entry` requires a package name"]);
            set entryPkgName = args[idx];
        } else if mem::eq(arg, "-test") {
            set buildTest = true;
        } else if mem::eq(arg, "-debug") {
            set debugEnabled = true;
        } else if mem::eq(arg, "-zero-bss") {
            set zeroBss = true;
        } else if mem::eq(arg, "-o") {
            try nextArg(args, &mut idx, &["`-o` requires an output path"]);
            set outputPath = args[idx];
        } else if mem::eq(arg, "-image") {
            let path = try nextArg(args, &mut idx, &["`-image` requires a binary RIL path"]);
            if imageCount == MAX_IMAGES { throw error(&["too many binary image inputs"]); }
            set imagePaths[imageCount] = path;
            set imageCount += 1;
        } else if mem::eq(arg, "-emit") {
            let mode = try nextArg(args, &mut idx, &["`-emit` requires `ril`"]);
            if not mem::eq(mode, "ril") {
                throw error(&["unknown output format", mode, "(expected: ril)"]);
            }
            set emitIl = true;
        } else if mem::eq(arg, "-dump") {
            try nextArg(args, &mut idx, &["`-dump` requires a mode (eg. ast)"]);
            let mode = args[idx];
            if mem::eq(mode, "ast") {
                set dump = Dump::Ast;
            } else if mem::eq(mode, "graph") {
                set dump = Dump::Graph;
            } else if mem::eq(mode, "il") {
                set dump = Dump::Il;
            } else if mem::eq(mode, "asm") {
                set dump = Dump::Asm;
            } else {
                throw error(&["unknown dump mode", mode, "(expected: ast, graph, il, asm)"]);
            }
        } else {
            throw error(&["unknown argument", arg]);
        }
        set idx += 1;
    }
    if emitIl and (outputPath == nil or dump <> Dump::None) {
        throw error(&["`-emit ril` requires `-o` and cannot be combined with `-dump`"]);
    }
    if (imageCount <> 0 or zeroBss) and (emitIl or (dump <> Dump::None and dump <> Dump::Asm)) {
        throw error(&["binary images and `-zero-bss` require native output"]);
    }
    if pkgCount == 0 {
        throw error(&["no package specified"]);
    }
    for i in 0..pkgCount {
        if inputs[i].radPathCount == 0 {
            throw error(&["package", inputs[i].name, "has no Radiance modules specified"]);
        }
        if emitIl and (inputs[i].asmPathCount <> 0 or inputs[i].startupPath <> nil) {
            throw error(&["binary RIL cannot contain assembly; link assembly when loading the RIL"]);
        }
    }

    // Determine entry package index.
    let mut entryPkgIdx: ?u32 = nil;
    if pkgCount == 1 {
        // Single package: it is the entry.
        set entryPkgIdx = 0;
    } else {
        // Multiple packages: need -entry.
        let entryName = entryPkgName else {
            throw error(&["`-entry` required when multiple packages specified"]);
        };
        for i in 0..pkgCount {
            if mem::eq(inputs[i].name, entryName) {
                set entryPkgIdx = i;
                break;
            }
        }
        if entryPkgIdx == nil {
            throw error(&["fatal:", "entry package", entryName, "not found"]);
        }
    }
    let entryIdx = entryPkgIdx else {
        panic "processCommand: no entry package";
    };
    for i in 0..pkgCount {
        if i <> entryIdx and inputs[i].startupPath <> nil {
            throw error(&["`-start` is only supported on the entry package"]);
        }
    }
    let graph = module::moduleGraph(&mut MODULE_ENTRIES[..], &mut STRING_POOL, arena);
    set *ctx = CompileContext {
        packages: undefined,
        inputs,
        packageCount: pkgCount,
        entryPkgIdx,
        graph,
        config: resolver::Config { buildTest },
        dump,
        outputPath,
        debug: debugEnabled,
        emitIl,
        imagePaths,
        imageCount,
        zeroBss,
    };
    // Initialize and parse all packages.
    let mut sourceArena = alloc::new(&mut MODULE_SOURCES[..]);
    for i in 0..pkgCount {
        package::init(&mut ctx.packages[i], i as u16, ctx.inputs[i].name, &mut STRING_POOL);

        for j in 0..ctx.inputs[i].radPathCount {
            let path = ctx.inputs[i].radPaths[j];
            try processModule(&mut ctx.packages[i], &mut ctx.graph, path, arena, &mut sourceArena);
        }
    }
}

/// Get the entry package from the context.
fn getEntryPackage(ctx: *CompileContext) -> *package::Package throws (Error) {
    let entryIdx = ctx.entryPkgIdx else {
        throw error(&["no entry package specified"]);
    };
    return &ctx.packages[entryIdx];
}

/// Return the startup assembly path for the entry package, if one was supplied.
fn getEntryStartupPath(ctx: *CompileContext) -> ?*[u8] {
    let entryIdx = ctx.entryPkgIdx else {
        panic "getEntryStartupPath: no entry package";
    };
    return ctx.inputs[entryIdx].startupPath;
}

/// Get root module info from a package.
fn getRootModule(pkg: *package::Package, graph: *module::ModuleGraph) -> RootModule throws (Error) {
    let rootId = pkg.rootModuleId else {
        throw error(&["no root module found"]);
    };
    let rootEntry = module::get(graph, rootId) else {
        throw error(&["root module entry not found"]);
    };
    let rootAst = rootEntry.ast else {
        throw error(&["root module has no AST"]);
    };
    return RootModule { entry: rootEntry, ast: rootAst };
}

/// Dump the module graph.
fn dumpGraph(ctx: *CompileContext) {
    let mut arena = alloc::new(&mut MAIN_ARENA[..]);
    module::printer::printGraph(&ctx.graph, &mut arena);
}

/// Dump the parsed AST.
fn dumpAst(ctx: *CompileContext) throws (Error) {
    let pkg = try getEntryPackage(ctx);
    let root = try getRootModule(pkg, &ctx.graph);
    let mut arena = alloc::new(&mut MAIN_ARENA[..]);

    ast::printer::printTree(root.ast, &mut arena);
}

/// Retain a lowered function and its entry role in an arena-owned RIL image.
fn collectLoweredFn(ctxPtr: *mut opaque, func: *il::Fn, role: lower::FnRole) {
    let ctx = ctxPtr as *mut IlSinkContext;
    ctx.functions.append(func, alloc::arenaAllocator(ctx.arena));
    if role == lower::FnRole::Default {
        set ctx.entry = func.name;
    }
}

/// Lower dependencies and the entry package into one binary RIL compilation unit.
fn lowerAllPackages(
    ctx: *mut CompileContext,
    res: *mut resolver::Resolver
) -> il::binary::Image throws (Error) {
    let entryPkg = try getEntryPackage(ctx);
    let options = lower::LowerOptions { debug: ctx.debug, buildTest: ctx.config.buildTest };
    let mut low = lower::lowerer(
        res, &ctx.graph, entryPkg.name, &mut res.arena, &mut res.arena, options
    );
    let mut sink = IlSinkContext { functions: &mut [], entry: nil, arena: &mut res.arena };
    set low.output = lower::FnOutput::Stream(lower::FnSink {
        ctx: &mut sink as *mut opaque, emitFn: collectLoweredFn,
    });
    try lowerAllPackagesInto(ctx, res, &mut low);
    return il::binary::Image {
        program: il::Program { data: low.data, fns: sink.functions },
        entry: sink.entry,
    };
}

/// Lower all packages into an existing lowerer.
fn lowerAllPackagesInto(
    ctx: *mut CompileContext,
    res: *mut resolver::Resolver,
    low: *mut lower::Lowerer
) throws (Error) {
    let entryIdx = ctx.entryPkgIdx else {
        panic "lowerAllPackagesInto: no entry package";
    };
    // Lower all packages except entry.
    for i in 0..ctx.packageCount {
        if i <> entryIdx {
            try lowerPackage(ctx, res, low, &mut ctx.packages[i], false);
        }
    }
    // Lower entry package.
    try lowerPackage(ctx, res, low, &mut ctx.packages[entryIdx], true);
}

/// Lower all modules in a package into the lowerer accumulator.
fn lowerPackage(
    ctx: *CompileContext,
    res: *mut resolver::Resolver,
    low: *mut lower::Lowerer,
    pkg: *mut package::Package,
    isEntry: bool
) throws (Error) {
    let rootId = pkg.rootModuleId else {
        throw error(&["no root module found"]);
    };
    // Set lowerer's package context for qualified name generation.
    // TODO: We shouldn't have to call this manually.
    lower::setPackage(low, &ctx.graph, pkg.name);

    try lowerModuleTreeInto(ctx, low, &ctx.graph, rootId, isEntry, pkg);
}

/// Recursively lower a module and all its children into the accumulator.
fn lowerModuleTreeInto(
    ctx: *CompileContext,
    low: *mut lower::Lowerer,
    graph: *module::ModuleGraph,
    modId: u16,
    isRoot: bool,
    pkg: *package::Package
) throws (Error) {
    let entry = module::get(graph, modId) else {
        throw error(&["module entry not found"]);
    };
    let modAst = entry.ast else {
        throw error(&["module has no AST"]);
    };
    pkgLog(pkg, &["lowering", "(", entry.filePath, ")", ".."]);

    try lower::lowerModule(low, modId, modAst, isRoot) catch err {
        io::printError("radiance: ");
        io::printError("internal error during lowering: ");
        lower::printError(err);
        io::printError("\n");

        throw Error::Other;
    };
    // Recurse into children.
    for i in 0..entry.childrenLen {
        let childId = module::childAt(entry, i);
        try lowerModuleTreeInto(ctx, low, graph, childId, false, pkg);
    }
}

/// Build a scope access chain: a::b::c from a slice of identifiers.
fn synthScopeAccess(arena: *mut ast::NodeArena, path: *[*[u8]]) -> *ast::Node {
    let mut result = ast::synthNode(
        arena,
        ast::NodeValue::Ident(strings::intern(&mut STRING_POOL, path[0]))
    );
    for i in 1..path.len {
        let child = ast::synthNode(
            arena,
            ast::NodeValue::Ident(strings::intern(&mut STRING_POOL, path[i]))
        );
        set result = ast::synthNode(arena, ast::NodeValue::ScopeAccess(ast::Access {
            parent: result, child,
        }));
    }
    return result;
}

/// Check if a function declaration has the `@test` attribute and return its name if so.
fn getTestFnName(decl: *ast::FnDecl) -> ?*[u8] {
    let attrs = decl.attrs else { return nil; };
    if not ast::attributesContains(&attrs, ast::Attribute::Test) {
        return nil;
    }
    let case ast::NodeValue::Ident(name) = decl.name.value
        else return nil;

    return name;
}

/// Scan a single module's AST for `@test` functions and append them to `tests`.
fn collectModuleTests(
    entry: *module::ModuleEntry,
    tests: *mut [TestDesc],
    testCount: *mut u32
) {
    let modAst = entry.ast else {
        return;
    };
    let case ast::NodeValue::Block(block) = modAst.value else {
        return;
    };
    let modPath = module::moduleQualifiedPath(entry);

    for stmt in block.statements {
        if let case ast::NodeValue::FnDecl(decl) = stmt.value {
            if let fnName = getTestFnName(&decl) {
                if *testCount < tests.len {
                    set tests[*testCount] = TestDesc { modPath, fnName };
                    set *testCount += 1;
                } else {
                    panic "collectModuleTests: too many tests";
                }
            }
        }
    }
}

/// Synthesize a `testing::test("mod", "name", mod::fn)` call for one test.
fn synthTestCall(arena: *mut ast::NodeArena, desc: *TestDesc) -> *ast::Node {
    let callee = synthScopeAccess(arena, &["testing", "test"]);
    let modStr = il::formatQualifiedName(
        &mut arena.arena,
        &desc.modPath[..desc.modPath.len - 1],
        desc.modPath[desc.modPath.len - 1]
    );
    let modArg = ast::synthNode(arena, ast::NodeValue::String(modStr));
    let nameArg = ast::synthNode(arena, ast::NodeValue::String(desc.fnName));

    // Intra-package path: skip the package name prefix.
    let mut funcPath: [*[u8]; 16] = undefined;
    for j in 1..desc.modPath.len {
        set funcPath[j - 1] = desc.modPath[j];
    }
    set funcPath[desc.modPath.len - 1] = desc.fnName;
    let funcArg = synthScopeAccess(arena, &funcPath[..desc.modPath.len]);

    let a = alloc::arenaAllocator(&mut arena.arena);
    let args = ast::nodeSlice(arena, 3)
        .append(modArg, a)
        .append(nameArg, a)
        .append(funcArg, a);

    return ast::synthNode(arena, ast::NodeValue::Call(ast::Call { callee, args }));
}

/// Inject a test runner into the entry package's root module.
///
/// Scans all parsed modules for `@test fn` declarations, then appends
/// a synthetic entry point to the root module's AST block:
///
/// ```
/// @default fn #testMain() -> i32 {
///     return testing::runAllTests(&[
///         testing::test("std::tests", "testFoo", tests::testFoo),
///         ...
///     ]);
/// }
/// ```
///
/// Uses `#`-prefixed names to avoid conflicts with user code.
fn generateTestRunner(
    ctx: *mut CompileContext,
    arena: *mut ast::NodeArena
) throws (Error) {
    let entryPkg = try getEntryPackage(ctx);
    let root = try getRootModule(entryPkg, &ctx.graph);

    // Collect all test functions across all modules.
    let mut tests: [TestDesc; MAX_TESTS] = undefined;
    let mut testCount: u32 = 0;

    for modIdx in 0..ctx.graph.entriesLen {
        if let entry = module::get(&ctx.graph, modIdx as u16) {
            collectModuleTests(entry, &mut tests[..], &mut testCount);
        }
    }
    if testCount == 0 {
        throw error(&["fatal:", "no test functions found"]);
    }
    let mut countBuf: [u8; 10] = undefined;
    let countStr = fmt::formatU32(testCount, &mut countBuf[..]);
    pkgLog(entryPkg, &["found", countStr, "test(s)"]);

    // Synthesize the `@default` function and append to the root module.
    let fnDecl = synthTestMainFn(arena, &tests[..testCount]);

    injectIntoBlock(root.ast, arena, fnDecl);
}

/// Synthesize the test entry point.
fn synthTestMainFn(arena: *mut ast::NodeArena, tests: *[TestDesc]) -> *ast::Node {
    // Build array literal: `[testing::test(...), ...]`.
    let a = alloc::arenaAllocator(&mut arena.arena);
    let mut elements = ast::nodeSlice(arena, tests.len as u32);
    for i in 0..tests.len {
        elements.append(synthTestCall(arena, &tests[i]), a);
    }
    let arrayLit = ast::synthNode(arena, ast::NodeValue::ArrayLit(elements));

    // Build: `&[...]`.
    let testsRef = ast::synthNode(arena, ast::NodeValue::AddressOf(ast::AddressOf {
        target: arrayLit, mutable: false,
    }));

    // Build: `testing::runAllTests(&[...])`.
    let runFn = synthScopeAccess(arena, &["testing", "runAllTests"]);
    let callArgs = ast::nodeSlice(arena, 1).append(testsRef, a);
    let callExpr = ast::synthNode(arena, ast::NodeValue::Call(ast::Call {
        callee: runFn, args: callArgs,
    }));

    // Build: `return testing::runAllTests(&[...]);`
    let retStmt = ast::synthNode(arena, ast::NodeValue::Return { value: callExpr });
    let bodyStmts = ast::nodeSlice(arena, 1).append(retStmt, a);
    let fnBody = ast::synthNode(arena, ast::NodeValue::Block(ast::Block { statements: bodyStmts }));

    // Build: `fn #testMain() -> i32`
    let fnName = ast::synthNode(arena, ast::NodeValue::Ident(strings::intern(&mut STRING_POOL, "#testMain")));
    let returnType = ast::synthNode(arena, ast::NodeValue::TypeSig(ast::TypeSig::Integer {
        width: 4, sign: ast::Signedness::Signed,
    }));
    let fnSig = ast::FnSig {
        params: ast::nodeSlice(arena, 0),
        returnType,
        throwList: ast::nodeSlice(arena, 0),
    };

    // `@default` attribute.
    let attrNode = ast::synthNode(arena, ast::NodeValue::Attribute(ast::Attribute::Default));
    let attrList = ast::nodeSlice(arena, 1).append(attrNode, a);
    let fnAttrs = ast::Attributes { list: attrList };

    return ast::synthNode(arena, ast::NodeValue::FnDecl(ast::FnDecl {
        name: fnName, sig: fnSig, body: fnBody, attrs: fnAttrs,
    }));
}

/// Append a declaration to a block node's statement list.
fn injectIntoBlock(
    blockNode: *mut ast::Node,
    arena: *mut ast::NodeArena,
    decl: *ast::Node
) {
    let case ast::NodeValue::Block(block) = blockNode.value else {
        panic "injectIntoBlock: expected Block node";
    };
    let stmts = block.statements.append(decl, alloc::arenaAllocator(&mut arena.arena));
    set blockNode.value = ast::NodeValue::Block(ast::Block { statements: stmts });
}

/// Write a self-contained RV64 image containing text and data sections.
fn writeImage(
    code: *[u32],
    roData: *[u8],
    rwData: *[u8],
    path: *[u8]
) -> bool {
    let mut header = rv64::imageHeader(code.len * rv64::INSTR_SIZE as u32, roData.len, rwData.len);
    let headerWords = &header[..];
    let headerBytes = @sliceOf(headerWords.ptr as *u8, headerWords.len * rv64::WORD_SIZE as u32);
    let codeBytes = @sliceOf(code.ptr as *u8, code.len * rv64::INSTR_SIZE as u32);

    return unix::writeFileParts(path, &[headerBytes, codeBytes, roData, rwData]);
}

/// Write a data section to a file at `basePath` + `ext`.
/// Empty data truncates any stale sidecar left by an earlier build.
fn writeDataWithExt(
    data: *[u8],
    basePath: *[u8],
    ext: *[u8]
) throws (Error) {
    let mut path: [u8; MAX_PATH_LEN] = undefined;
    let mut pos: u32 = 0;

    set pos += try! mem::copy(&mut path[pos..], basePath);
    set pos += try! mem::copy(&mut path[pos..], ext);
    set path[pos] = 0; // Null-terminate for syscall.

    if not unix::writeFile(&path[..pos], data) {
        throw error(&["fatal:", "failed to write data file"]);
    }
}

/// Serialize debug entries and write the `.debug` file.
/// Resolves module IDs to file paths via the module graph.
/// Format per entry is `{pc: u32,  offset: u32, filePath: [u8], NULL}`.
fn writeDebugInfo(
    entries: *[types::DebugEntry],
    graph: *module::ModuleGraph,
    basePath: *[u8],
    arena: *mut alloc::Arena
) throws (Error) {
    if entries.len == 0 {
        return;
    }
    // Use remaining arena space as serialization buffer.
    let buf = alloc::remainingBuf(arena);
    let mut pos: u32 = 0;

    for i in 0..entries.len {
        let entry = &entries[i];
        let modEntry = module::get(graph, entry.moduleId) else {
            panic "writeDebugInfo: module not found for debug entry";
        };
        set pos += try! mem::copy(&mut buf[pos..], @sliceOf(&entry.pc as *u8, 4));
        set pos += try! mem::copy(&mut buf[pos..], @sliceOf(&entry.offset as *u8, 4));
        set pos += try! mem::copy(&mut buf[pos..], modEntry.filePath);

        set buf[pos] = 0;
        set pos += 1;
    }
    try writeDataWithExt(&buf[..pos], basePath, DEBUG_EXT);
}

/// Run the resolver on the parsed modules.
fn runResolver(ctx: *mut CompileContext, nodeCount: u32) -> resolver::Resolver throws (Error) {
    let mut mainArena = alloc::new(&mut MAIN_ARENA[..]);
    let entryPkg = try getEntryPackage(ctx);

    pkgLog(entryPkg, &["resolving", ".."]);

    let nodeDataSize = nodeCount * @sizeOf(resolver::NodeData);
    let nodeDataPtr = try! alloc::alloc(&mut mainArena, nodeDataSize, @alignOf(resolver::NodeData));
    let nodeData = @sliceOf(nodeDataPtr as *mut resolver::NodeData, nodeCount);
    let storage = resolver::ResolverStorage {
        arena: mainArena,
        nodeData,
        pkgScope: &mut RESOLVER_PKG_SCOPE,
        errors: &mut RESOLVER_ERRORS[..],
    };
    let mut res = resolver::resolver(storage, ctx.config);

    // Build the semantic package list consumed by the resolver.
    let mut resolverPkgs: [resolver::Pkg; MAX_PACKAGES] = undefined;
    let mut resolverPackageCount: u32 = 0;
    for i in 0..ctx.packageCount {
        let pkg = &ctx.packages[i];
        let root = try getRootModule(pkg, &ctx.graph);

        set resolverPkgs[resolverPackageCount] = resolver::Pkg {
            rootEntry: root.entry,
            rootAst: root.ast,
        };
        set resolverPackageCount += 1;
    }

    // Resolve all packages.
    // TODO: Fix this error printing dance.
    let diags = try resolver::resolve(&mut res, &ctx.graph, &resolverPkgs[..resolverPackageCount]) catch {
        let diags = resolver::Diagnostics { errors: res.errors };
        resolver::printer::printDiagnostics(&diags, &res);
        throw Error::Other;
    };
    if not resolver::success(&diags) {
        resolver::printer::printDiagnostics(&diags, &res);
        let mut countBuf: [u8; 10] = undefined;
        let countStr = fmt::formatU32(diags.errors.len, &mut countBuf[..]);
        throw error(&["failed:", countStr, "errors"]);
    }
    return res;
}

/// Emit one lowered function to machine code and reclaim its IL arena.
fn generateLoweredFn(ctxPtr: *mut opaque, func: *il::Fn, role: lower::FnRole) {
    let ctx = ctxPtr as *mut CodegenSinkContext;

    match role {
        case lower::FnRole::Default => {
            rv64::recordFunctionAlias(ctx.generator, DEFAULT_ENTRY_SYMBOL);
            match ctx.generator.entryPatch {
                case rv64::EntryPatch::Reserved(_) => {
                    set ctx.generator.entryPatch = rv64::EntryPatch::Reserved(func.name);
                }
                // No entry jump was reserved: startup assembly calls the
                // default function through `DEFAULT_ENTRY_SYMBOL` instead.
                case rv64::EntryPatch::None => {}
            }
        }
        else => {}
    }
    rv64::generateFunction(ctx.generator, func, ctx.fnArena);
    alloc::reset(ctx.fnArena);
}

/// Assemble one `.ras` input and merge it into the active code generator.
///
/// Text symbols are appended to `generator`. Data emitted by the assembler is
/// copied into `ASM_RO_DATA_BUF` at `*asmDataLen`, and `*asmDataLen` is advanced
/// so the next assembly module receives the correct rodata base address.
fn assembleAsmModule(
    generator: *mut rv64::Generator,
    pkg: *package::Package,
    path: *[u8],
    asmDataLen: *mut u32,
    arena: *mut alloc::Arena
) throws (Error) {
    pkgLog(pkg, &["asm:", "parsing", "(", path, ")", ".."]);

    let source = unix::readFile(path, &mut ASM_SOURCE_BUF[..]) else {
        throw error(&["error reading assembly file"]);
    };
    if source.len == ASM_SOURCE_BUF.len {
        throw error(&["fatal:", "assembly source too large:", path]);
    }
    let program = try asm::assemble(
        asm::scanner::SourceKind::File { path },
        source,
        &mut ASM_TEXT_BUF[..],
        &mut ASM_DATA_BUF[..],
        arena,
        &mut STRING_POOL,
        rv64::RO_DATA_BASE + *asmDataLen
    ) catch {
        throw error(&["assembly failed:", path]);
    };
    if *asmDataLen + program.data.len > ASM_RO_DATA_BUF.len {
        throw error(&["fatal:", "assembly rodata too large"]);
    }
    try! mem::copy(&mut ASM_RO_DATA_BUF[*asmDataLen..], program.data);
    set *asmDataLen += program.data.len;

    rv64::addAssembly(generator, program);
}

/// Assemble all inputs collected in the package inputs.
fn assembleAsmInputs(
    ctx: *CompileContext,
    generator: *mut rv64::Generator,
    asmDataLen: *mut u32,
    arena: *mut alloc::Arena
) -> *[u8] throws (Error) {
    for i in 0..ctx.packageCount {
        let input = &ctx.inputs[i];
        for j in 0..input.asmPathCount {
            try assembleAsmModule(
                generator,
                &ctx.packages[i],
                input.asmPaths[j],
                asmDataLen,
                arena
            );
        }
    }
    return &ASM_RO_DATA_BUF[..*asmDataLen];
}

/// Lower all packages while streaming each lowered function into RV64 codegen.
fn lowerAndGenerateAllPackages(
    ctx: *mut CompileContext,
    res: *mut resolver::Resolver,
    fnArena: *mut alloc::Arena,
    codegenOptions: CodegenOptions
) -> rv64::Program throws (Error) {
    let entryIdx = ctx.entryPkgIdx else {
        panic "lowerAndGenerateAllPackages: no entry package";
    };
    let entryPkg = &ctx.packages[entryIdx];
    let startupPath = getEntryStartupPath(ctx);
    let options = lower::LowerOptions { debug: ctx.debug, buildTest: ctx.config.buildTest };
    let storage = rv64::Storage {
        dataSyms: &mut CODEGEN_DATA_SYMS[..],
        dataSymEntries: &mut CODEGEN_DATA_SYM_ENTRIES[..],
    };
    let mut entryPatch = rv64::EntryPatch::None;
    match codegenOptions.entryMode {
        case CodegenEntryMode::DefaultEntry => {
            set entryPatch = rv64::EntryPatch::Reserved(nil);
        }
        else => {}
    }
    let mut generator = rv64::beginProgram(
        rv64::ProgramOptions { entryPatch, debug: codegenOptions.debug },
        &mut res.arena
    );
    let mut codegenCtx = CodegenSinkContext {
        generator: &mut generator,
        fnArena,
    };
    let mut low = lower::lowerer(
        res, &ctx.graph, entryPkg.name, &mut res.arena, fnArena, options
    );
    set low.output = lower::FnOutput::Stream(lower::FnSink {
        ctx: &mut codegenCtx as *mut opaque,
        emitFn: generateLoweredFn,
    });
    let mut asmDataLen: u32 = 0;
    if let path = startupPath {
        try assembleAsmModule(&mut generator, entryPkg, path, &mut asmDataLen, &mut res.arena);
    }
    try lowerAllPackagesInto(ctx, res, &mut low);
    let asmData = try assembleAsmInputs(ctx, &mut generator, &mut asmDataLen, &mut res.arena);
    try images::append(&mut generator, &ctx.imagePaths[..ctx.imageCount], &mut STRING_POOL,
        &mut res.arena, fnArena, &mut low.data) catch e {
        throw error(&[e.message]);
    };
    if ctx.zeroBss {
        for i in 0..low.data.len {
            let item = &mut low.data[i];
            if not item.isZeroInit { continue; }
            let value = try! alloc::alloc(&mut res.arena, @sizeOf(il::DataValue), @alignOf(il::DataValue)) as *mut il::DataValue;
            set *value = il::DataValue { item: il::DataItem::Undef, count: item.size };
            set item.values = @sliceOf(value, 1);
            set item.isZeroInit = false;
        }
    }
    try binary::layout(&low.data[..], asmData.len) catch e {
        throw error(&[e.message]);
    };

    match generator.entryPatch {
        case rv64::EntryPatch::Reserved(targetName) => {
            if targetName == nil {
                throw error(&["fatal:", "no default function found"]);
            }
        }
        else => {}
    }
    if let path = codegenOptions.logPath {
        pkgLog(entryPkg, &["generating code", "(", path, ")", ".."]);
    }
    return rv64::finishProgram(&mut generator, &low.data[..], storage, asmData, &mut RO_DATA_BUF[..], &mut RW_DATA_BUF[..]);
}

/// Lower, optionally dump, and optionally generate binary output.
fn compile(
    ctx: *mut CompileContext,
    res: *mut resolver::Resolver,
    fnArena: *mut alloc::Arena
) throws (Error) {
    let entryPkg = try getEntryPackage(ctx);
    let mut out = sexpr::Output::Stdout;

    if ctx.emitIl {
        let path = ctx.outputPath else { throw error(&["binary RIL output requires a path"]); };
        let image = try lowerAllPackages(ctx, res);
        try binary::write(&image, path, &mut res.arena) catch {
            throw error(&["failed to write binary RIL", path]);
        };
        return;
    }

    if ctx.dump == Dump::Il {
        // Lower all packages into a single unified IL program for dumping.
        let image = try lowerAllPackages(ctx, res);
        il::printer::printProgram(&mut out, &image.program);
        io::print("\n");
        return;
    }
    if ctx.dump == Dump::Asm {
        let result = try lowerAndGenerateAllPackages(ctx, res, fnArena, CodegenOptions {
            logPath: nil,
            debug: false,
            entryMode: CodegenEntryMode::None,
        });
        printer::printCodeTo(&mut out, entryPkg.name, result.code, result.funcs, &mut res.arena);
        io::print("\n");

        return;
    }
    // Generate binary output if path specified.
    let outPath = ctx.outputPath else {
        try lowerAllPackages(ctx, res);
        return;
    };
    let startupPath = getEntryStartupPath(ctx);
    let result = try lowerAndGenerateAllPackages(ctx, res, fnArena, CodegenOptions {
        logPath: outPath,
        debug: ctx.debug,
        entryMode: CodegenEntryMode::None
            if startupPath <> nil
            else CodegenEntryMode::DefaultEntry,
    });

    if not writeImage(
        result.code,
        &RO_DATA_BUF[..result.roDataSize],
        &RW_DATA_BUF[..result.rwDataSize],
        outPath
    ) {
        throw error(&["fatal:", "failed to write output file"]);
    }

    // Write debug info file if enabled.
    if ctx.debug {
        try writeDebugInfo(result.debugEntries, &ctx.graph, outPath, &mut res.arena);
    }
    pkgLog(entryPkg, &["ok", "(", outPath, ")"]);
}

@default fn main(env: *sys::Env) -> i32 {
    if env.args.len > 0 and mem::eq(env.args[0], "-load") {
        return binary::run(env.args, &mut STRING_POOL);
    }
    if env.args.len > 0 and mem::eq(env.args[0], "-catalog") {
        return catalogCommand(env.args);
    }
    let mut arena = ast::nodeArena(&mut TEMP_ARENA[..]);
    let ctx = &mut CONTEXT;
    try processCommand(env.args, &mut arena, ctx) catch {
        return 1;
    };
    match ctx.dump {
        case Dump::Ast => {
            try dumpAst(ctx) catch {
                return 1;
            };
            return 0;
        }
        case Dump::Graph => {
            dumpGraph(ctx);
            return 0;
        }
        else => {}
    }
    // Generate test runner if in test mode.
    if ctx.config.buildTest {
        try generateTestRunner(ctx, &mut arena) catch {
            return 1;
        };
    }
    // Run resolution phase.
    let mut res = try runResolver(ctx, arena.nextId) catch {
        return 1;
    };
    let mut fnArena = alloc::new(&mut FN_ARENA[..]);

    // Lower, dump, and/or generate output.
    try compile(ctx, &mut res, &mut fnArena) catch {
        return 1;
    };
    return 0;
}