radiance · Radiance self-hosting compiler

compiler/ radiance/ radiance.rad 53.7 KiB lib/ scripts/ seed/ sublime/ test/ vim/ .gitignore 336 B .gitsigners 112 B CELL_PERMISSIONS 6.8 KiB CONTRIBUTING 2.1 KiB LICENSE 1.1 KiB Makefile 5.4 KiB README 2.5 KiB STYLE 2.5 KiB std.lib 1.5 KiB std.lib.test 808 B
compiler/radiance.rad 53.7 KiB raw
//! Radiance compiler front-end.
mod codegen;

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::emit;
use std::arch::rv64::printer;
use std::lang::sexpr;
use std::lang::gen::data;
use std::lang::il::binary;
use std::lang::il::binary::collect;
use std::lang::il::binary::program;
use std::lang::gen::labels;
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 = 128;
/// Maximum number of packages we can compile.
constant MAX_PACKAGES: u32 = 4;
/// Source code buffer arena (4 MB).
constant MAX_SOURCES_SIZE: u32 = 4194304;
/// 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;

/// Byte size of the five u32 fields in a single-file RV64 image header.
constant IMAGE_HEADER_SIZE: u32 = @sizeOf([u32; 5]);

/// AST arena size (64 MB) - retains parsed nodes throughout compilation.
constant TEMP_ARENA_SIZE: u32 = 67108864;
/// Per-function lowering and register-allocation arena size (24 MB).
constant FN_ARENA_SIZE: u32 = 25165824;
/// Main arena size (208 MB) - lives throughout compilation.
/// Used for: resolver data, types, symbols, global IL data, and codegen output.
constant MAIN_ARENA_SIZE: u32 = 218103808;

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

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

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

/// Code generation storage.
unsafe static CODEGEN_DATA_SYMS: [data::DataSym; data::MAX_DATA_SYMS] = undefined;
/// Hash table entries for data symbol lookup.
unsafe static CODEGEN_DATA_SYM_ENTRIES: [dict::Entry; data::DATA_SYM_TABLE_SIZE] = undefined;
/// Emitted instruction storage.
static CODEGEN_INSTRUCTIONS: [u32; emit::MAX_INSTRS] = [0; emit::MAX_INSTRS];
/// Local branch patch storage.
unsafe static CODEGEN_PENDING_BRANCHES: [emit::PendingBranch; emit::MAX_PENDING] = undefined;
/// Function call patch storage.
unsafe static CODEGEN_PENDING_CALLS: [emit::PendingCall; emit::MAX_PENDING] = undefined;
/// Assembly jump patch storage.
unsafe static CODEGEN_PENDING_JUMPS: [emit::PendingJump; emit::MAX_PENDING] = undefined;
/// Address load patch storage.
unsafe static CODEGEN_PENDING_ADDR_LOADS: [emit::PendingAddrLoad; emit::MAX_PENDING] = undefined;
/// Per-function block offset storage.
static CODEGEN_BLOCK_OFFSETS: [i32; labels::MAX_BLOCKS_PER_FN] = [0; labels::MAX_BLOCKS_PER_FN];
/// Function label hash table storage.
unsafe static CODEGEN_FUNC_ENTRIES: [dict::Entry; labels::FUNC_TABLE_SIZE] = undefined;
/// Printed function address storage.
unsafe static CODEGEN_FUNCS: [types::FuncAddr; emit::MAX_FUNCS] = undefined;
/// Debug location storage.
unsafe static CODEGEN_DEBUG_ENTRIES: [types::DebugEntry; emit::MAX_DEBUG_ENTRIES] = undefined;

/// Maximum number of exported definitions in one binary package.
constant MAX_PACKAGE_EXPORTS: u32 = 8192;
/// Maximum number of indexed names in one binary package.
constant MAX_PACKAGE_SYMBOLS: u32 = 16384;
/// Export workspace reused for each binary package.
unsafe static PACKAGE_EXPORTS: [binary::Export; MAX_PACKAGE_EXPORTS] = undefined;
/// Symbol workspace reused for each binary package.
static PACKAGE_SYMBOLS: [*[u8]; MAX_PACKAGE_SYMBOLS] = [""; MAX_PACKAGE_SYMBOLS];

/// 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] = [0; MAX_RO_DATA_SIZE];
/// Read-write data buffer.
static RW_DATA_BUF: [u8; MAX_RW_DATA_SIZE] = [0; MAX_RW_DATA_SIZE];
/// Assembly module source buffer.
static ASM_SOURCE_BUF: [u8; MAX_SOURCES_SIZE] = [0; MAX_SOURCES_SIZE];
/// Temporary assembly text buffer.
static ASM_TEXT_BUF: [u32; 262144] = [0; 262144];
/// Temporary assembly data buffer.
static ASM_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = [0; MAX_RO_DATA_SIZE];
/// Accumulated assembly read-only data.
static ASM_RO_DATA_BUF: [u8; MAX_RO_DATA_SIZE] = [0; MAX_RO_DATA_SIZE];

/// Assembly source file extension.
constant ASM_SOURCE_EXT: *[u8] = ".ras";
/// Symbol name exported for startup code to call the semantic entry function.
export 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> [-o <output> | -ril <directory>]\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,
}

/// Validated command-line compilation options.
record Command {
    /// Number of packages to compile.
    packageCount: u32,
    /// Index of the selected entry package.
    entryPkgIdx: u32,
    /// Resolver configuration.
    config: resolver::Config,
    /// What to dump during compilation.
    dump: Dump,
    /// Output path for binary.
    outputPath: ?*[u8],
    /// Output directory for separate binary RIL packages.
    rilDirectory: ?*[u8],
    /// Whether to emit debug info (.debug file).
    debug: bool,
}

/// Compilation context.
record CompileContext: 'permission {
    /// 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 'permission,
    /// Resolver configuration.
    config: resolver::Config,
    /// What to dump during compilation.
    dump: Dump,
    /// Output path for binary.
    outputPath: ?*[u8],
    /// Output directory for separate binary RIL packages.
    rilDirectory: ?*[u8],
    /// Whether to emit debug info (.debug file).
    debug: bool,
}

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

/// 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: [""; MAX_LOADED_MODULES],
        radPathCount: 0,
        asmPaths: [""; MAX_ASM_MODULES],
        asmPathCount: 0,
    };
}

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

    let moduleId = try package::registerModule(pkg, graph, &mut STRING_POOL, path) catch {
        throw error(&["error registering module"]);
    };
    // Read file into remaining arena space.
    let buffer = alloc::remainingBuf(&mut *sourceArena);
    if buffer.len == 0 {
        throw error(&["fatal:", "source arena exhausted"]);
    }
    let sourceLen = unix::readFile(path, buffer) else {
        throw error(&["error reading file"]);
    };
    let source = &buffer[..sourceLen];
    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];
}

/// Parse and validate command-line inputs and compilation options.
fn parseCommand(
    args: *[*[u8]],
    inputs: &mut [PackageInput]
) -> Command throws (Error) {
    let mut buildTest = false;
    let mut debugEnabled = false;
    let mut outputPath: ?*[u8] = nil;
    let mut rilDirectory: ?*[u8] = nil;
    let mut dump = Dump::None;
    let mut entryPkgName: ?*[u8] = nil;

    // Per-package source path tracking.
    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 >= inputs.len {
                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, "-o") {
            try nextArg(args, &mut idx, &["`-o` requires an output path"]);
            set outputPath = args[idx];
        } else if mem::eq(arg, "-ril") {
            try nextArg(args, &mut idx, &["`-ril` requires an output directory"]);
            set rilDirectory = args[idx];
        } 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 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"]);
        }
    }

    // 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 "parseCommand: 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"]);
        }
    }
    if rilDirectory <> nil and (outputPath <> nil or dump <> Dump::None) {
        throw error(&["`-ril` requires a separate invocation from `-o` or `-dump`"]);
    }
    return Command {
        packageCount: pkgCount,
        entryPkgIdx: entryIdx,
        config: resolver::Config { buildTest },
        dump,
        outputPath,
        rilDirectory,
        debug: debugEnabled,
    };
}

/// Parse CLI arguments and return compilation context.
unsafe fn processCommand 'permission (
    args: *[*[u8]],
    arena: &mut ast::NodeArena,
    permission: &'permission mut module::Permission
) -> CompileContext 'permission throws (Error) {
    let mut inputs = [packageInput(""); MAX_PACKAGES];
    let command = try parseCommand(args, &mut inputs[..]);
    let graph = module::moduleGraph(&mut MODULE_ENTRIES[..], arena, permission);
    let mut ctx = CompileContext 'permission {
        packages: undefined,
        inputs,
        packageCount: command.packageCount,
        entryPkgIdx: command.entryPkgIdx,
        graph,
        config: command.config,
        dump: command.dump,
        outputPath: command.outputPath,
        rilDirectory: command.rilDirectory,
        debug: command.debug,
    };
    // Initialize and parse all packages.
    let mut sourceArena = alloc::new(&mut MODULE_SOURCES[..]);
    for i in 0..ctx.packageCount {
        let name = ctx.inputs[i].name;
        package::init(&mut ctx.packages[i], i as u16, 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);
        }
    }
    return ctx;
}

/// Get the entry package from the context.
fn getEntryPackage 'permission (ctx: &CompileContext 'permission) -> 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 'permission (ctx: &CompileContext 'permission) -> ?*[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 'permission (pkg: &package::Package, graph: &module::ModuleGraph 'permission) -> 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 = module::astFor(graph, rootEntry) else {
        throw error(&["root module has no AST"]);
    };
    return RootModule { entry: rootEntry, ast: rootAst };
}

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

/// Dump the parsed AST.
unsafe fn dumpAst 'permission (ctx: &CompileContext 'permission) 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);
}

/// Lower all packages into a single IL program.
/// Dependencies are lowered first, then the entry package.
unsafe fn lowerAllPackages 'arena 'permission (
    ctx: &CompileContext 'permission,
    res: *unsafe mut resolver::Resolver 'arena
) -> il::Program throws (Error) {
    let entryIdx = ctx.entryPkgIdx else {
        panic "lowerAllPackages: no entry package";
    };
    let entryPkg = &ctx.packages[entryIdx];

    // Create the lowerer accumulator using entry package's name.
    let options = lower::LowerOptions { debug: ctx.debug, buildTest: ctx.config.buildTest };
    let arena = (&mut *res.arena) as *unsafe mut alloc::Arena;
    let resolved: 'phase = &*res where 'arena: 'phase in {
        let mut low = lower::lowerer(resolved, entryPkg.name, arena, options);
        try lowerAllPackagesInto(ctx, &mut low, &mut *arena);

        // Finalize and return the unified program.
        return lower::finalize(low);
    }
}

/// Lower all packages into an existing lowerer.
unsafe fn lowerAllPackagesInto 'arena 'phase 'permission (
    ctx: &CompileContext 'permission,
    low: &mut lower::Lowerer 'arena 'phase,
    functionArena: &mut alloc::Arena
) throws (Error) where 'arena: 'phase {
    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, low, &ctx.packages[i], false, functionArena);
        }
    }
    // Lower entry package.
    try lowerPackage(ctx, low, &ctx.packages[entryIdx], true, functionArena);
}

/// Lower all modules in a package into the lowerer accumulator.
unsafe fn lowerPackage 'arena 'phase 'permission (
    ctx: &CompileContext 'permission,
    low: &mut lower::Lowerer 'arena 'phase,
    pkg: &package::Package,
    isEntry: bool,
    functionArena: &mut alloc::Arena
) throws (Error) where 'arena: 'phase {
    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, pkg.name);

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

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

    try lower::lowerModule(low, modId, modAst, isRoot, functionArena) 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..module::childCount(graph, entry) {
        let childId = module::childAt(graph, entry, i);
        try lowerModuleTreeInto(low, graph, childId, false, pkg, functionArena);
    }
}

/// Build a scope access chain: a::b::c from a slice of identifiers.
unsafe 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 'permission (graph: &module::ModuleGraph 'permission, entry: *module::ModuleEntry, tests: &mut [?TestDesc], testCount: &mut u32) {
    let modAst = module::astFor(graph, entry) 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";
                }
            }
        }
    }
}

/// Collect initialized test descriptors from one package in module order.
fn collectPackageTests 'permission (graph: &module::ModuleGraph 'permission, packageId: u16, tests: &mut [?TestDesc]) -> u32 {
    let mut count: u32 = 0;
    for modIdx in 0..module::entryCount(graph) {
        if let entry = module::get(graph, modIdx as u16) {
            if entry.packageId == packageId {
                collectModuleTests(graph, entry, tests, &mut count);
            }
        }
    }
    return count;
}

/// Synthesize a `testing::test("mod", "name", mod::fn)` call for one test.
unsafe 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] = [""; 16];
    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 the entry package 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.
unsafe fn generateTestRunner 'permission (ctx: *unsafe mut CompileContext 'permission, arena: &mut ast::NodeArena) throws (Error) {
    let entryPkg = try getEntryPackage(ctx);
    let root = try getRootModule(&entryPkg, &ctx.graph);

    // Collect test functions from the entry package's modules.
    let mut tests: [?TestDesc; MAX_TESTS] = [nil; MAX_TESTS];
    let testCount = collectPackageTests(&ctx.graph, entryPkg.id, &mut tests[..]);
    if testCount == 0 {
        throw error(&["fatal:", "no test functions found"]);
    }
    let mut countBuf: [u8; 10] = [0; 10];
    let start = fmt::formatU32(testCount, &mut countBuf[..]);
    io::printError("radiance: ");
    io::printError(entryPkg.name);
    io::printError(": found ");
    io::printError(&countBuf[start..]);
    io::printError(" test(s)\n");

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

    let updatedRoot = injectIntoBlock(root.ast, arena, fnDecl);
    try module::setAst(&mut ctx.graph, root.entry.id, updatedRoot) catch {
        throw error(&["failed to set test runner AST"]);
    };
}

/// Synthesize the test entry point.
unsafe 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 {
        let desc = tests[i] else panic "synthTestMainFn: missing active test";
        elements.append(synthTestCall(arena, &desc), a);
    }
    let arrayLit = ast::synthNode(arena, ast::NodeValue::ArrayLit(elements));

    // Build: `&[...]`.
    let testsRef = ast::synthNode(arena, ast::NodeValue::AddressOf(ast::AddressOf {
        target: arrayLit, kind: ast::AddressKind::Shared, permission: nil,
    }));

    // 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, isUnsafe: false }));

    // Build: `unsafe 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),
    };

    // Entry and function safety attributes.
    let attrNode = ast::synthNode(arena, ast::NodeValue::Attribute(ast::Attribute::Default));
    let unsafeAttr = ast::synthNode(arena, ast::NodeValue::Attribute(ast::Attribute::Unsafe));
    let attrList = ast::nodeSlice(arena, 2).append(attrNode, a).append(unsafeAttr, a);
    let fnAttrs = ast::Attributes { list: attrList };

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

/// Build a block node with a declaration appended to its statement list.
unsafe fn injectIntoBlock(
    blockNode: *ast::Node,
    arena: &mut ast::NodeArena,
    decl: *ast::Node
) -> *ast::Node {
    let case ast::NodeValue::Block(block) = blockNode.value else {
        panic "injectIntoBlock: expected Block node";
    };
    let allocator = alloc::arenaAllocator(&mut arena.arena);
    let mut stmts = ast::nodeSlice(arena, block.statements.len + 1);
    for stmt in block.statements {
        stmts.append(stmt, allocator);
    }
    stmts.append(decl, allocator);
    return ast::allocNode(arena, blockNode.span, ast::NodeValue::Block(
        ast::Block { statements: stmts, isUnsafe: block.isUnsafe }
    ));
}

/// Write a self-contained RV64 image containing text and data sections.
fn writeImage(
    code: &[u8],
    roData: &[u8],
    rwData: &[u8],
    path: *[u8]
) -> bool {
    let header = rv64::imageHeader(code.len, roData.len, rwData.len);
    let mut headerBytes = [0 as u8; IMAGE_HEADER_SIZE];
    assert headerBytes.len == header.len * @sizeOf(u32);
    for word, index in header {
        for byte in 0..@sizeOf(u32) {
            set headerBytes[index * @sizeOf(u32) + byte] = (word >> (byte * 8)) as u8;
        }
    }

    let fd = unix::openOpts(path, unix::OpenFlags(*unix::O_WRONLY | *unix::O_CREAT | *unix::O_TRUNC), 420);
    if fd < 0 {
        return false;
    }
    let written = unix::writeAll(fd, &headerBytes[..]) and unix::writeAll(fd, code)
        and unix::writeAll(fd, roData) and unix::writeAll(fd, rwData);
    let closed = unix::close(fd) == 0;
    return written and closed;
}

/// 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] = [0; MAX_PATH_LEN];
    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 'permission (
    entries: &[types::DebugEntry],
    graph: &module::ModuleGraph 'permission,
    basePath: *[u8],
    buf: &mut [u8]
) throws (Error) {
    if entries.len == 0 {
        return;
    }
    // The caller supplies the serialization buffer.
    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";
        };
        for value in [entry.pc, entry.offset] {
            for i in 0..@sizeOf(u32) {
                set buf[pos] = (value >> (i * 8)) as u8;
                set pos += 1;
            }
        }
        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.
unsafe fn runResolver 'arena 'permission (
    ctx: &CompileContext 'permission,
    mainArena: &'arena mut alloc::Arena,
    nodeCount: u32
) -> resolver::Resolver 'arena throws (Error) {
    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 {
        nodeData,
        pkgScope: &mut RESOLVER_PKG_SCOPE,
        errors: &mut RESOLVER_ERRORS[..],
    };
    let mut res = resolver::resolver(mainArena, 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(&mut res);
        resolver::printer::printDiagnostics(&diags, &res, &ctx.graph);
        throw Error::Other;
    };
    if not resolver::success(&diags) {
        resolver::printer::printDiagnostics(&diags, &res, &ctx.graph);
        let mut countBuf: [u8; 10] = undefined;
        let start = fmt::formatU32(diags.errors.len, &mut countBuf[..]);
        io::printError("radiance: failed: ");
        io::printError(&countBuf[start..]);
        io::printError(" errors\n");
        throw Error::Other;
    }
    return res;
}

/// 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.
unsafe 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 sourceLen = unix::readFile(path, &mut ASM_SOURCE_BUF[..]) else {
        throw error(&["error reading assembly file"]);
    };
    let input = &ASM_SOURCE_BUF[..sourceLen];
    if input.len == ASM_SOURCE_BUF.len {
        throw error(&["fatal:", "assembly source too large:", path]);
    }
    // Assembly symbols borrow source bytes until final linking.
    let buffer = try alloc::allocSlice(arena, 1, 1, input.len) catch {
        throw error(&["assembly source workspace exhausted"]);
    };
    let source = buffer as *mut [u8];
    try! mem::copy(source, input);
    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.
unsafe fn assembleAsmInputs 'permission (
    ctx: &CompileContext 'permission,
    generator: &mut rv64::Generator,
    asmDataLen: &mut u32,
    arena: &mut alloc::Arena
) -> *[u8] throws (Error) {
    for i in 0..ctx.packageCount {
        for j in 0..ctx.inputs[i].asmPathCount {
            try assembleAsmModule(
                generator,
                &ctx.packages[i],
                ctx.inputs[i].asmPaths[j],
                asmDataLen,
                arena
            );
        }
    }
    return &ASM_RO_DATA_BUF[..*asmDataLen];
}

/// Generate dependency packages before the entry package.
unsafe fn generateAllPackagesInto 'arena 'phase 'permission (
    ctx: &CompileContext 'permission,
    low: &mut lower::Lowerer 'arena 'phase,
    generator: &mut rv64::Generator,
    fnArena: &mut alloc::Arena
) throws (Error) where 'arena: 'phase {
    let entryIdx = ctx.entryPkgIdx else panic "generateAllPackagesInto: no entry package";
    for i in 0..ctx.packageCount {
        if i <> entryIdx {
            try generatePackageInto(ctx, low, &ctx.packages[i], false, generator, fnArena);
        }
    }
    try generatePackageInto(ctx, low, &ctx.packages[entryIdx], true, generator, fnArena);
}

/// Generate all functions in one package.
unsafe fn generatePackageInto 'arena 'phase 'permission (
    ctx: &CompileContext 'permission,
    low: &mut lower::Lowerer 'arena 'phase,
    pkg: &package::Package,
    isEntry: bool,
    generator: &mut rv64::Generator,
    fnArena: &mut alloc::Arena
) throws (Error) where 'arena: 'phase {
    let rootId = pkg.rootModuleId else throw error(&["no root module found"]);
    lower::setPackage(low, pkg.name);
    try generateModuleTree(ctx, low, rootId, isEntry, pkg, generator, fnArena);
}

/// Lower and consume each function before visiting the next declaration.
unsafe fn generateModuleTree 'arena 'phase 'permission (
    ctx: &CompileContext 'permission,
    low: &mut lower::Lowerer 'arena 'phase,
    modId: u16,
    isRoot: bool,
    pkg: &package::Package,
    generator: &mut rv64::Generator,
    fnArena: &mut alloc::Arena
) throws (Error) where 'arena: 'phase {
    let entry = module::get(&ctx.graph, modId)
        else throw error(&["module entry not found"]);
    let modAst = module::astFor(&ctx.graph, entry)
        else throw error(&["module has no AST"]);
    pkgLog(pkg, &["lowering", "(", entry.filePath, ")", ".."]);
    set low.currentMod = modId;
    let mut cursor = try lower::moduleCursor(modAst, isRoot) catch err {
        io::printError("radiance: internal error during lowering: ");
        lower::printError(err);
        io::printError("\n");
        throw Error::Other;
    };
    loop {
        let result = try lower::lowerNext(low, &mut cursor, fnArena) catch err {
            io::printError("radiance: internal error during lowering: ");
            lower::printError(err);
            io::printError("\n");
            throw Error::Other;
        };
        let next = result else break;
        codegen::emit(generator, fnArena, &*next.function, next.role);
    }
    for i in 0..module::childCount(&ctx.graph, entry) {
        let childId = module::childAt(&ctx.graph, entry, i);
        try generateModuleTree(ctx, low, childId, false, pkg, generator, fnArena);
    }
}

/// Lower all packages while streaming each lowered function into RV64 codegen.
unsafe fn lowerAndGenerateAllPackages 'arena 'permission (
    ctx: &CompileContext 'permission,
    res: *unsafe mut resolver::Resolver 'arena,
    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 emitterStorage = emit::Storage {
        code: &mut CODEGEN_INSTRUCTIONS[..],
        pendingBranches: &mut CODEGEN_PENDING_BRANCHES[..],
        pendingCalls: &mut CODEGEN_PENDING_CALLS[..],
        pendingJumps: &mut CODEGEN_PENDING_JUMPS[..],
        pendingAddrLoads: &mut CODEGEN_PENDING_ADDR_LOADS[..],
        blockOffsets: &mut CODEGEN_BLOCK_OFFSETS[..],
        funcEntries: &mut CODEGEN_FUNC_ENTRIES[..],
        funcs: &mut CODEGEN_FUNCS[..],
        debugEntries: &mut CODEGEN_DEBUG_ENTRIES[..],
    };
    let mut generator = rv64::beginProgramWithStorage(
        rv64::ProgramOptions {
            entryPatch,
            debug: codegenOptions.debug,
            placement: rv64::image::Placement::Hosted,
        },
        emitterStorage
    );
    let arena = (&mut *res.arena) as *unsafe mut alloc::Arena;
    let resolved: 'phase = &*res where 'arena: 'phase in {
        let mut low = lower::lowerer(resolved, entryPkg.name, arena, options);
        let mut asmDataLen: u32 = 0;
        if let path = startupPath {
            try assembleAsmModule(&mut generator, entryPkg, path, &mut asmDataLen, arena);
        }
        try generateAllPackagesInto(
            ctx, &mut low, &mut generator, fnArena
        );
        let asmData = try assembleAsmInputs(ctx, &mut generator, &mut asmDataLen, arena);
        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 try rv64::finishProgram(
            generator, low.data, storage, asmData,
            &mut RO_DATA_BUF[..], &mut RW_DATA_BUF[..]
        ) catch err {
            match err {
                case rv64::Error::Allocation => throw error(&["code generation workspace exhausted"]),
                case rv64::Error::Capacity => throw error(&["code generation output capacity exceeded"]),
                case rv64::Error::Symbol => throw error(&["code generation has an unresolved symbol"]),
                case rv64::Error::Relocation => throw error(&["code generation relocation is out of range"]),
                case rv64::Error::Image(_) => throw error(&["code generation image layout is invalid"]),
                case rv64::Error::Data(_) => throw error(&["code generation data layout is invalid"]),
            }
        };
    }
}

/// Source exports selected for one binary RIL package.
record PackageExports: Copy {
    /// Number of initialized entries in the caller's export table.
    count: u32,
    /// Default function entry.
    entry: ?*[u8],
}

/// Collect exported definitions and the default entry from a package's source modules.
unsafe fn packageExports 'permission (
    ctx: &CompileContext 'permission,
    pkg: &package::Package,
    ilProgram: &il::Program,
    exports: &mut [binary::Export],
    arena: &mut alloc::Arena
) -> PackageExports throws (Error) {
    let mut count: u32 = 0;
    let mut entryName: ?*[u8] = nil;
    for i in 0..module::entryCount(&ctx.graph) {
        let modEntry = module::get(&ctx.graph, i as u16) else continue;
        if modEntry.packageId <> pkg.id {
            continue;
        }
        let root = module::astFor(&ctx.graph, modEntry) else continue;
        let case ast::NodeValue::Block(block) = root.value else continue;
        for node in block.statements {
            let mut ident: ?*ast::Node = nil;
            let mut attrs: ?ast::Attributes = nil;
            let mut kind = binary::ExportKind::Function;
            match node.value {
                case ast::NodeValue::FnDecl(decl) => {
                    set ident = decl.name;
                    set attrs = decl.attrs;
                },
                case ast::NodeValue::ConstDecl(decl) => {
                    set ident = decl.ident; set attrs = decl.attrs; set kind = binary::ExportKind::Data;
                },
                case ast::NodeValue::StaticDecl(decl) => {
                    set ident = decl.ident; set attrs = decl.attrs; set kind = binary::ExportKind::Data;
                },
                else => continue,
            }
            let attributes = attrs else continue;
            if ast::attributesContains(&attributes, ast::Attribute::Intrinsic) {
                continue;
            }
            let isDefault = ast::attributesContains(&attributes, ast::Attribute::Default)
                and pkg.rootModuleId == modEntry.id;
            if not isDefault and not ast::attributesContains(&attributes, ast::Attribute::Export) {
                continue;
            }
            let nameNode = ident else continue;
            let case ast::NodeValue::Ident(name) = nameNode.value else continue;
            let qualified = il::formatQualifiedName(arena, module::moduleQualifiedPath(modEntry), name);
            let mut present = false;
            match kind {
                case binary::ExportKind::Function => {
                    for func in ilProgram.fns {
                        if mem::eq(func.name, qualified) {
                            set present = true;
                        }
                    }
                },
                case binary::ExportKind::Data => {
                    for item in ilProgram.data {
                        if mem::eq(item.name, qualified) {
                            set present = true;
                        }
                    }
                },
            }
            if not present {
                continue;
            }
            if count == exports.len {
                throw error(&["too many package exports"]);
            }
            set exports[count] = binary::Export { name: qualified, kind };
            set count += 1;
            if isDefault {
                set entryName = qualified;
            }
        }
    }
    return PackageExports { count, entry: entryName };
}

/// Write encoded binary RIL bytes into an existing directory.
fn writePackage(bytes: &[u8], directory: *[u8], name: *[u8]) throws (Error) {
    let mut path = [0 as u8; MAX_PATH_LEN];
    let mut pos: u32 = 0;
    for part in &[directory, "/", name, ".ril"] {
        set pos += try mem::copy(&mut path[pos..MAX_PATH_LEN - 1], part) catch {
            throw error(&["binary RIL output path is too long"]);
        };
    }
    set path[pos] = 0;
    if not unix::writeFile(&path[..pos], bytes) {
        throw error(&["cannot write binary RIL package", name]);
    }
}

/// Emit one binary RIL file per package into an existing directory.
unsafe fn emitPackages 'arena 'permission (
    ctx: &CompileContext 'permission,
    res: *unsafe mut resolver::Resolver 'arena,
    directory: *[u8]
) throws (Error) {
    for i in 0..ctx.packageCount {
        if ctx.inputs[i].asmPathCount > 0 or ctx.inputs[i].startupPath <> nil {
            throw error(&["binary RIL output requires Radiance source modules"]);
        }
    }
    let unified = try lowerAllPackages(ctx, res);
    let allocator = alloc::arenaAllocator(&mut *res.arena);
    for i in 0..ctx.packageCount {
        let pkg = &ctx.packages[i];
        let mut dataItems: *mut [il::Data] = &mut [];
        let mut functions: *unsafe mut [*unsafe il::Fn] = &mut [];
        for item in unified.data {
            if ownsSymbol(pkg.name, item.name) {
                dataItems.append(item, allocator);
            }
        }
        for func in unified.fns {
            if ownsSymbol(pkg.name, func.name) {
                functions.append(func, allocator);
            }
        }
        let local = il::Program { data: &dataItems[..], fns: functions };
        let selected = try packageExports(ctx, pkg, &local, &mut PACKAGE_EXPORTS[..], &mut *res.arena);
        let mut dependencies: [*[u8]; MAX_PACKAGES] = [""; MAX_PACKAGES];
        let symbolTable: 'names = &mut PACKAGE_SYMBOLS[..], dependencyTable = &mut dependencies[..] in {
            let mut names = collect::new(symbolTable, dependencyTable);
            let image = try collect::package(&mut names, pkg.name, local, &PACKAGE_EXPORTS[..selected.count], selected.entry) catch {
                throw error(&["cannot collect binary RIL package", pkg.name]);
            };
            let length = try program::encode(&mut FN_ARENA[..], &image) catch {
                throw error(&["binary RIL output capacity exceeded", pkg.name]);
            };
            try writePackage(&FN_ARENA[..length], directory, pkg.name);
        }
    }
}

/// Match a qualified definition to its package name.
fn ownsSymbol(owner: *[u8], name: *[u8]) -> bool {
    let suffix = mem::stripPrefix(owner, name) else return false;
    return suffix.len > 2 and suffix[0] == ':' and suffix[1] == ':';
}

/// Lower, optionally dump, and optionally generate binary output.
unsafe fn compile 'arena 'permission (
    ctx: &CompileContext 'permission,
    res: *unsafe mut resolver::Resolver 'arena,
    fnArena: &mut alloc::Arena
) throws (Error) {
    let entryPkg = try getEntryPackage(ctx);
    if let directory = ctx.rilDirectory {
        try emitPackages(ctx, res, directory);
        return;
    }
    let mut out = sexpr::Stdout {};

    if ctx.dump == Dump::Il {
        // Lower all packages into a single unified IL program for dumping.
        let program = try lowerAllPackages(ctx, res);
        il::printer::printProgram(&mut out, &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);
        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,
        }
    );

    let codeBytes = @sliceOf(result.code.ptr as *u8, result.code.len * rv64::INSTR_SIZE as u32);
    if not writeImage(
        codeBytes,
        &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 {
        let buf = alloc::remainingBuf(&mut *res.arena);
        try writeDebugInfo(result.debugEntries, &ctx.graph, outPath, &mut buf[..]);
    }
    pkgLog(&entryPkg, &["ok", "(", outPath, ")"]);
}

@default unsafe fn main(env: *sys::Env) -> i32 {
    let mut owner = module::Permission {};
    let permission: 'permission = &mut owner in {
        let mut arena = ast::nodeArena(&mut TEMP_ARENA[..]);
        let mut ctx = try processCommand(env.args, &mut arena, permission) 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(&mut ctx, &mut arena) catch {
                return 1;
            };
        }
        // Run resolution phase.
        let mut mainArena = alloc::new(&mut MAIN_ARENA[..]);
        let arenaRef: 'arena = &mut mainArena, context = &ctx in {
            let mut res = try runResolver(
                context, arenaRef, arena.nextId
            ) catch {
                return 1;
            };
            let mut fnArena = alloc::new(&mut FN_ARENA[..]);

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