# Notes and random stuff

TODO

DEBUG

NOTES

AGENTS.md

CLAUDE.md

/notes

/tools

/.research

/.claude

# Compiler/build output

/bin

*.rv64

*.rv64.ro.data

*.rv64.rw.data

*.rv64.debug

*.o

# Seed binary (tracked, but not stage intermediates)

!seed/

!seed/*

seed/radiance.rv64.s*

# Backups we don't want to check-in

*.backup

# Library test files

lib/std.test*

alexis ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAICpDRmIwBm4ajzW+METm9tBdK4CG2/v0qmO4bPfi+s+c alexis@radiant.computer

Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer)

Permission is hereby granted, free of charge, to any person obtaining a copy of

this software and associated documentation files (the "Software"), to deal in

the Software without restriction, including without limitation the rights to

use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies

of the Software, and to permit persons to whom the Software is furnished to do

so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all

copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

SOFTWARE.

# Radiance build file.

# Core standard library modules.

STD := -pkg std $(patsubst %,-mod %,$(shell cat std.lib))

# Full standard library with test modules.

STD_TEST := $(STD) $(patsubst %,-mod %,$(shell cat std.lib.test))

# Source files.

STD_LIB := $(shell find lib -name '*.rad')

RAD_BIN := bin/radiance.rv64.dev

# Emulator command used to invoke the self-hosted compiler.

EMU       := $(or $(RAD_EMULATOR),emulator)

EMU_FLAGS := -memory-size=385024 \

			 -data-size=348160 \

			 -stack-size=512

RADIANCE  := $(EMU) $(EMU_FLAGS) -run $(RAD_BIN)

# Verify the emulator binary exists.

EMU_PATH := $(shell command -v $(EMU) 2>/dev/null)

default: emulator $(RAD_BIN)

test: emulator std-test lower-test asm-test

# Emulator command check

emulator:

ifeq ($(EMU_PATH),)

	$(error Emulator not found. Install it or set RAD_EMULATOR to its path)

endif

# Compiler build

SEED      := seed/radiance.rv64

SEED_OPTS := $(STD) -pkg radiance -mod compiler/radiance.rad -entry radiance

$(RAD_BIN): $(STD_LIB) compiler/radiance.rad

	@echo "radiance $(SEED) => $@"

	@$(EMU) $(EMU_FLAGS) -run $(SEED) $(SEED_OPTS) -o $@

# Standard Library Tests

STD_LIB_TEST := lib/std.test.rv64

std-test: $(STD_LIB_TEST)

	@echo

	@$(EMU) $(EMU_FLAGS) -run $(STD_LIB_TEST)

$(STD_LIB_TEST): $(STD_LIB) $(RAD_BIN)

	@echo "radiance -test $(STD_TEST) -entry std -o $@"

	@$(RADIANCE) -test $(STD_TEST) -entry std -o $@

clean-std-test:

	@rm -f lib/std.test.rv64 \

		lib/std.test.rv64.debug \

		lib/std.test.rv64.s \

		lib/std.test.rv64.o \

		lib/std.test.rv64.rw.data \

		lib/std.test.rv64.ro.data

# Lowering Tests

LOWER_TEST     := test/lower/lower-test.rv64

LOWER_TEST_RUN := test/lower/run

lower-test: $(LOWER_TEST)

	@echo

	@$(LOWER_TEST_RUN)

$(LOWER_TEST): test/lower/lower-test.rad $(STD_LIB) $(RAD_BIN)

	@echo "radiance $(STD) -pkg lower -mod test/lower/lower-test.rad -entry lower -o $@"

	@$(RADIANCE) $(STD) -pkg lower -mod test/lower/lower-test.rad -entry lower -o $@

clean-lower-test:

	@rm -f $(LOWER_TEST) \

		test/lower/lower-test.rv64.debug \

		test/lower/lower-test.rv64.s \

		test/lower/lower-test.rv64.o \

		test/lower/lower-test.rv64.rw.data \

		test/lower/lower-test.rv64.ro.data

# Code generation tests.

ASM_TEST_DIR := lib/std/arch/rv64/tests

ASM_TEST_SRC := $(wildcard $(ASM_TEST_DIR)/*.rad)

ASM_TEST_BIN := $(ASM_TEST_SRC:.rad=.rv64)

ASM_TEST_RUN := test/asm/run

asm-test: $(ASM_TEST_BIN) $(RAD_BIN)

	@echo

	@$(ASM_TEST_RUN) $(ASM_TEST_SRC)

$(ASM_TEST_DIR)/%.rv64: $(ASM_TEST_DIR)/%.rad $(RAD_BIN)

	@echo "radiance $< => $@"

	@$(RADIANCE) -pkg test -mod $< -o $@

clean-asm-test:

	@rm -f $(ASM_TEST_BIN) \

		$(wildcard $(ASM_TEST_DIR)/*.rv64.debug) \

		$(wildcard $(ASM_TEST_DIR)/*.rv64.s) \

		$(wildcard $(ASM_TEST_DIR)/*.rv64) \

		$(wildcard $(ASM_TEST_DIR)/*.rv64.rw.data) \

		$(wildcard $(ASM_TEST_DIR)/*.rv64.ro.data)

seed:

	seed/update

clean-rad:

	rm -f $(RAD_BIN) $(RAD_BIN).ro.data $(RAD_BIN).rw.data

	rm -f seed/radiance.rv64.s[0-9]*

clean: clean-std-test clean-lower-test clean-asm-test clean-rad

t: test

c: clean

.PHONY: test clean default std-test lower-test asm-test seed \

	clean-std-test clean-lower-test clean-asm-test clean-rad emulator

.SUFFIXES:

.DELETE_ON_ERROR:

.SILENT:

 \ | /

-     -

 / | \

RADIANCE

Radiance is a small statically-typed systems language designed for the Radiant

computer system (https://radiant.computer). It currently targets RISC-V (RV64).

The compiler is self-hosted: written in Radiance, it compiles to RISC-V and

runs inside a RISC-V emulator on x86-64 platforms.

REQUIREMENTS

  * Linux on x86-64

  * Make

  * Radiant's RISC-V Emulator

    (https://code.radiant.computer/emulator/)

BUILDING

  The compiler is self-hosted, so building from source requires bootstrapping

  from a seed binary. A known-good compiler is checked into the repository.

  The Radiant emulator is required to run the compiler and build process

  on x86-64. The build process will look for it in $PATH, unless $RAD_EMULATOR

  is set to its location:

      export RAD_EMULATOR=~/bin/emulator

  Then, build the compiler:

      make

  This uses the emulator to run the seed binary (`seed/radiance.rv64`) which

  compiles the self-hosted compiler source to produce `bin/radiance.rv64.dev`.

  To update the seed to a new fixed point:

      make seed

  This iterates self-compilation stages until two consecutive stages produce

  identical output, proving the compiler faithfully reproduces itself. See

  `seed/README` for full details on the seed workflow, verification, and

  how to handle breaking changes.

USAGE

  Compile a Radiance program:

      emulator -run bin/radiance.rv64.dev \

          -pkg example -mod example.rad -o example.rv64

  Run a compiled binary:

      emulator -run example.rv64

TESTING

  Run all tests:

      make test

  Individual test suites:

      make std-test    # Standard library tests

      make lower-test  # IL lowering tests

      make asm-test    # RV64 code generation tests

PROJECT STRUCTURE

  seed/            Seed compiler binary and update tooling

  compiler/        Self-hosted compiler entry point

  lib/std/         Standard library

  lib/std/lang/    Compiler modules

  lib/std/arch/    Architecture backends

  test/            Test harnesses

  scripts/         Utility scripts

  vim/             Vim syntax files

EDITOR SUPPORT

  Vim syntax files for Radiance (.rad) and RIL (.ril) are in the vim/ folder.

  Copy them to ~/.vim/syntax/ for syntax highlighting.

LICENSE

  Licensed under the MIT License,

  Copyright (c) 2025-2026 Radiant Computer (https://radiant.computer)

//! Radiance compiler front-end.

use std::mem;

use std::fmt;

use std::io;

use std::lang::alloc;

use std::lang::ast;

use std::lang::parser;

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::printer;

use std::lang::sexpr;

use std::sys;

use std::sys::unix;

/// Maximum number of modules we can load per package.

const MAX_LOADED_MODULES: u32 = 64;

/// Maximum number of packages we can compile.

const MAX_PACKAGES: u32 = 4;

/// Total module entries across all packages.

const MAX_TOTAL_MODULES: u32 = 192;

/// Source code buffer arena (2 MB).

const MAX_SOURCES_SIZE: u32 = 2097152;

/// Maximum number of test functions we can discover.

const MAX_TESTS: u32 = 1024;

/// Temporary arena size (32 MB) - retains all parsed AST until resolution.

/// Used for: AST during parsing, then codegen scratch space.

const TEMP_ARENA_SIZE: u32 = 33554432;

/// Main arena size (128 MB) - lives throughout compilation.

/// Used for: resolver data, types, symbols, lowered IL.

const MAIN_ARENA_SIZE: u32 = 134217728;

/// Temporary storage arena - reusable between phases.

static TEMP_ARENA: [u8; TEMP_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: [rv64::DataSym; rv64::MAX_DATA_SYMS] = undefined;

/// Debug info file extension.

const DEBUG_EXT: *[u8] = ".debug";

/// Read-only data file extension.

const RO_DATA_EXT: *[u8] = ".ro.data";

/// Read-write data file extension.

const RW_DATA_EXT: *[u8] = ".rw.data";

/// Maximum rodata size (1MB).

const MAX_RO_DATA_SIZE: u32 = 1048576;

/// Maximum rwdata size (1MB).

const MAX_RW_DATA_SIZE: u32 = 1048576;

/// Maximum path length.

const 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;

/// Usage string.

const USAGE: *[u8] =

    "usage: radiance -pkg <name> -mod <input>.. [-pkg <name> -mod <input>..] -entry <pkg> -o <output>\n";

/// Compiler error.

union Error {

    Other,

}

/// What to dump during compilation.

union Dump {

    /// 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 {

    /// Full module qualified path segments (eg. ["std", "tests"]).

    modPath: *[*[u8]],

    /// Test function name (eg. "testFoo").

    fnName: *[u8],

}

/// Compilation context.

record CompileContext {

    /// Array of packages to compile.

    packages: [package::Package; 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,

}

/// Root module info for a package.

record RootModule {

    entry: *module::ModuleEntry,

    ast: *mut ast::Node,

}

/// 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");

}

/// 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 {

        io::printError("radiance: error registering module\n");

        throw Error::Other;

    };

    // Read file into remaining arena space.

    let buffer = alloc::remainingBuf(sourceArena);

    if buffer.len == 0 {

        io::printError("radiance: fatal: source arena exhausted\n");

        throw Error::Other;

    }

    let source = unix::readFile(path, buffer) else {

        io::printError("radiance: error reading file\n");

        throw Error::Other;

    };

    if source.len == buffer.len {

        io::printError("radiance: fatal: source arena too small, file truncated: ");

        io::printError(path);

        io::printError("\n");

        throw Error::Other;

    }

    // Commit only what was read.

    alloc::commit(sourceArena, source.len);

    let ast = try parser::parse(source, nodeArena, &mut STRING_POOL) catch {

        io::printError("radiance: error parsing module\n");

        throw Error::Other;

    };

    try module::setAst(graph, moduleId, ast) catch {

        io::printError("radiance: error setting AST\n");

        throw Error::Other;

    };

    try module::setSource(graph, moduleId, source) catch {

        io::printError("radiance: error setting source\n");

        throw Error::Other;

    };

}

/// Parse CLI arguments and return compilation context.

fn processCommand(

    args: *[*[u8]],

    arena: *mut ast::NodeArena

) -> 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;

    // Per-package module path tracking.

    let mut moduleCounts: [u32; MAX_PACKAGES] = undefined;

    let mut modulePaths: [[*[u8]; MAX_LOADED_MODULES]; MAX_PACKAGES] = undefined;

    let mut pkgNames: [*[u8]; MAX_PACKAGES] = undefined;

    let mut pkgCount: u32 = 0;

    let mut currentPkgIdx: ?u32 = nil;

    for i in 0..MAX_PACKAGES {

        moduleCounts[i] = 0;

    }

    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") {

            idx = idx + 1;

            if idx >= args.len {

                io::printError("radiance: `-pkg` requires a package name\n");

                throw Error::Other;

            }

            if pkgCount >= MAX_PACKAGES {

                io::printError("radiance: too many packages specified\n");

                throw Error::Other;

            }

            pkgNames[pkgCount] = args[idx];

            currentPkgIdx = pkgCount;

            pkgCount = pkgCount + 1;

        } else if mem::eq(arg, "-mod") {

            idx = idx + 1;

            if idx >= args.len {

                io::printError("radiance: `-mod` requires a module path\n");

                throw Error::Other;

            }

            let pkgIdx = currentPkgIdx else {

                io::printError("radiance: `-mod` must follow a `-pkg` argument\n");

                throw Error::Other;

            };

            if moduleCounts[pkgIdx] >= MAX_LOADED_MODULES {

                io::printError("radiance: too many modules specified for package\n");

                throw Error::Other;

            }

            modulePaths[pkgIdx][moduleCounts[pkgIdx]] = args[idx];

            moduleCounts[pkgIdx] = moduleCounts[pkgIdx] + 1;

        } else if mem::eq(arg, "-entry") {

            idx = idx + 1;

            if idx >= args.len {

                io::printError("radiance: `-entry` requires a package name\n");

                throw Error::Other;

            }

            entryPkgName = args[idx];

        } else if mem::eq(arg, "-test") {

            buildTest = true;

        } else if mem::eq(arg, "-debug") {

            debugEnabled = true;

        } else if mem::eq(arg, "-o") {

            idx = idx + 1;

            if idx >= args.len {

                io::printError("radiance: `-o` requires an output path\n");

                throw Error::Other;

            }

            outputPath = args[idx];

        } else if mem::eq(arg, "-dump") {

            idx = idx + 1;

            if idx >= args.len {

                io::printError("radiance: `-dump` requires a mode (eg. ast)\n");

                throw Error::Other;

            }

            let mode = args[idx];

            if mem::eq(mode, "ast") {

                dump = Dump::Ast;

            } else if mem::eq(mode, "graph") {

                dump = Dump::Graph;

            } else if mem::eq(mode, "il") {

                dump = Dump::Il;

            } else if mem::eq(mode, "asm") {

                dump = Dump::Asm;

            } else {

                io::printError("radiance: unknown dump mode `");

                io::printError(mode);

                io::printError("` (expected: ast, graph, il, asm)\n");

                throw Error::Other;

            }

        } else {

            io::printError("radiance: unknown argument `");

            io::printError(arg);

            io::printError("`\n");

            throw Error::Other;

        }

        idx = idx + 1;

    }

    if pkgCount == 0 {

        io::printError("radiance: no package specified\n");

        throw Error::Other;

    }

    // Determine entry package index.

    let mut entryPkgIdx: ?u32 = nil;

    if pkgCount == 1 {

        // Single package: it is the entry.

        entryPkgIdx = 0;

    } else {

        // Multiple packages: need -entry.

        let entryName = entryPkgName else {

            io::printError("radiance: `-entry` required when multiple packages specified\n");

            throw Error::Other;

        };

        for i in 0..pkgCount {

            if mem::eq(pkgNames[i], entryName) {

                entryPkgIdx = i;

                break;

            }

        }

        if entryPkgIdx == nil {

            io::printError("radiance: fatal: entry package `");

            io::printError(entryName);

            io::printError("` not found\n");

            throw Error::Other;

        }

    }

    let graph = module::moduleGraph(&mut MODULE_ENTRIES[..], &mut STRING_POOL, arena);

    let mut ctx = CompileContext {

        packages: undefined,

        packageCount: pkgCount,

        entryPkgIdx,

        graph,

        config: resolver::Config { buildTest },

        dump,

        outputPath,

        debug: debugEnabled,

    };

    // Initialize and parse all packages.

    let mut sourceArena = alloc::new(&mut MODULE_SOURCES[..]);

    for i in 0..pkgCount {

        try! package::init(&mut ctx.packages[i], i as u16, pkgNames[i], &mut STRING_POOL);

        for j in 0..moduleCounts[i] {

            let path = modulePaths[i][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(ctx: *CompileContext) -> *package::Package throws (Error) {

    let entryIdx = ctx.entryPkgIdx else {

        io::printError("radiance: no entry package specified\n");

        throw Error::Other;

    };

    return &ctx.packages[entryIdx];

}

/// Get root module info from a package.

fn getRootModule(pkg: *package::Package, graph: *module::ModuleGraph) -> RootModule throws (Error) {

    let rootId = pkg.rootModuleId else {

        io::printError("radiance: no root module found\n");

        throw Error::Other;

    };

    let rootEntry = module::get(graph, rootId) else {

        io::printError("radiance: root module entry not found\n");

        throw Error::Other;

    };

    let rootAst = rootEntry.ast else {

        io::printError("radiance: root module has no AST\n");

        throw Error::Other;

    };

    return RootModule { entry: rootEntry, ast: rootAst };

}

/// Dump the module graph.

fn dumpGraph(ctx: *CompileContext) throws (Error) {

    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);

}

/// Lower all packages into a single IL program.

/// Dependencies are lowered first, then the entry package.

fn lowerAllPackages(

    ctx: *mut CompileContext,

    res: *mut resolver::Resolver

) -> 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 mut low = lower::lowerer(res, &ctx.graph, entryPkg.name, &mut res.arena, options);

    // Lower all packages except entry.

    for i in 0..ctx.packageCount {

        if i != entryIdx {

            try lowerPackage(ctx, res, &mut low, &mut ctx.packages[i], false);

        }

    }

    // Lower entry package.

    let defaultFn = try lowerPackage(ctx, res, &mut low, &mut ctx.packages[entryIdx], true);

    // Finalize and return the unified program.

    return lower::finalize(&low, defaultFn);

}

/// 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

) -> ?u32 throws (Error) {

    let rootId = pkg.rootModuleId else {

        io::printError("radiance: no root module found\n");

        throw Error::Other;

    };

    // 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);

    return 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

) -> ?u32 throws (Error) {

    let entry = module::get(graph, modId) else {

        io::printError("radiance: module entry not found\n");

        throw Error::Other;

    };

    let modAst = entry.ast else {

        io::printError("radiance: module has no AST\n");

        throw Error::Other;

    };

    pkgLog(pkg, &["lowering", "(", entry.filePath, ")", ".."]);

    let defaultFn = try lower::lowerModule(low, modId, modAst, isRoot) catch err {

        io::printError("radiance: 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);

    }

    return defaultFn;

}

/// 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]))

        );

        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 i in 0..block.statements.len {

        let stmt = block.statements.list[i];

        if let case ast::NodeValue::FnDecl(decl) = stmt.value {

            if let fnName = getTestFnName(&decl) {

                if *testCount < tests.len {

                    tests[*testCount] = TestDesc { modPath, fnName };

                    *testCount = *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 {

        funcPath[j - 1] = desc.modPath[j];

    }

    funcPath[desc.modPath.len - 1] = desc.fnName;

    let funcArg = synthScopeAccess(arena, &funcPath[..desc.modPath.len]);

    let mut args = ast::nodeList(arena, 3);

    ast::nodeListPush(&mut args, modArg);

    ast::nodeListPush(&mut args, nameArg);

    ast::nodeListPush(&mut args, funcArg);

    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 {

        io::printError("radiance: fatal: no test functions found\n");

        throw Error::Other;

    }

    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 mut elements = ast::nodeList(arena, tests.len);

    for i in 0..tests.len {

        ast::nodeListPush(&mut elements, synthTestCall(arena, &tests[i]));

    }

    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 mut callArgs = ast::nodeList(arena, 1);

    ast::nodeListPush(&mut callArgs, testsRef);

    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 mut bodyStmts = ast::nodeList(arena, 1);

    ast::nodeListPush(&mut bodyStmts, retStmt);

    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::nodeList(arena, 0),

        returnType,

        throwList: ast::nodeList(arena, 0),

    };

    // `@default` attribute.

    let attrNode = ast::synthNode(arena, ast::NodeValue::Attribute(ast::Attribute::Default));

    let mut attrList = ast::nodeList(arena, 1);

    ast::nodeListPush(&mut attrList, attrNode);

    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 mut stmts = block.statements;

    ast::nodeListGrow(&mut stmts, arena, 1);

    ast::nodeListPush(&mut stmts, decl);

    blockNode.value = ast::NodeValue::Block(ast::Block { statements: stmts });

}

/// Write code buffer to file as raw bytes.

fn writeCode(code: *[u32], path: *[u8]) -> bool {

    // Convert `u32` slice to `u8` slice (little-endian).

    let byteLen = code.len * 4;

    let bytePtr = code.ptr as *u8;

    let bytes = @sliceOf(bytePtr, byteLen);

    return unix::writeFile(path, bytes);

}

/// Write a data section to a file at `basePath` + `ext`.

/// If the data is empty, no file is written.

fn writeDataWithExt(

    data: *[u8],

    basePath: *[u8],

    ext: *[u8]

) throws (Error) {

    if data.len == 0 {

        return;

    }

    let mut path: [u8; MAX_PATH_LEN] = undefined;

    let mut pos: u32 = 0;

    pos = pos + try! mem::copy(&mut path[pos..], basePath);

    pos = pos + try! mem::copy(&mut path[pos..], ext);

    path[pos] = 0; // Null-terminate for syscall.

    if not unix::writeFile(&path[..pos], data) {

        io::printError("radiance: fatal: failed to write data file\n");

        throw Error::Other;

    }

}

/// 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: *[rv64::emit::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";

        };

        pos = pos + try! mem::copy(buf[pos..], @sliceOf(&entry.pc as *u8, 4));

        pos = pos + try! mem::copy(buf[pos..], @sliceOf(&entry.offset as *u8, 4));

        pos = pos + try! mem::copy(buf[pos..], modEntry.filePath);

        buf[pos] = 0;

        pos = 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 package inputs.

    let mut packages: [resolver::Pkg; MAX_PACKAGES] = undefined;

    for i in 0..ctx.packageCount {

        let pkg = &ctx.packages[i];

        let root = try getRootModule(pkg, &ctx.graph);

        packages[i] = resolver::Pkg {

            rootEntry: root.entry,

            rootAst: root.ast,

        };

    }

    // Resolve all packages.

    // TODO: Fix this error printing dance.

    let diags = try resolver::resolve(&mut res, &ctx.graph, &packages[..ctx.packageCount]) 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);

        io::print("radiance: failed: ");

        io::printU32(diags.errors.listLen);

        io::printLn(" errors");

        throw Error::Other;

    }

    return res;

}

/// Lower, optionally dump, and optionally generate binary output.

fn compile(ctx: *mut CompileContext, res: *mut resolver::Resolver) throws (Error) {

    let entryPkg = try getEntryPackage(ctx);

    // Lower all packages into a single unified IL program.

    // Dependencies must be lowered before the packages that use them.

    let program = try lowerAllPackages(ctx, res);

    let mut out = sexpr::Output::Stdout;

    if ctx.dump == Dump::Il {

        il::printer::printProgram(&mut out, &mut res.arena, &program);

        io::print("\n");

        return;

    }

    if ctx.dump == Dump::Asm {

        // TODO: Why do we generate code in two places?

        let result = rv64::generate(&program, rv64::Storage { dataSyms: &mut CODEGEN_DATA_SYMS[..] }, &mut RO_DATA_BUF[..], &mut RW_DATA_BUF[..], &mut res.arena, false);

        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 {

        return;

    };

    // Check that we have an entry point.

    if program.defaultFnIdx == nil {

        io::printError("radiance: fatal: no default function found\n");

        throw Error::Other;

    }

    pkgLog(entryPkg, &["generating code", "(", outPath, ")", ".."]);

    let storage = rv64::Storage { dataSyms: &mut CODEGEN_DATA_SYMS[..] };

    let result = rv64::generate(&program, storage, &mut RO_DATA_BUF[..], &mut RW_DATA_BUF[..], &mut res.arena, ctx.debug);

    if not writeCode(result.code, outPath) {

        io::printError("radiance: fatal: failed to write output file\n");

        throw Error::Other;

    }

    // Write data files.

    try writeDataWithExt(&RO_DATA_BUF[..result.roDataSize], outPath, RO_DATA_EXT);

    try writeDataWithExt(&RW_DATA_BUF[..result.rwDataSize], outPath, RW_DATA_EXT);

    // 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 {

    let mut arena = ast::nodeArena(&mut TEMP_ARENA[..]);

    let mut ctx = try processCommand(env.args, &mut arena) catch {

        return 1;

    };

    match ctx.dump {

        case Dump::Ast => {

            try dumpAst(&ctx) catch {

                return 1;

            };

            return 0;

        }

        case Dump::Graph => {

            try dumpGraph(&ctx) catch {

                return 1;

            };

            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 res = try runResolver(&mut ctx, arena.nextId) catch {

        return 1;

    };

    // Lower, dump, and/or generate output.

    try compile(&mut ctx, &mut res) catch {

        return 1;

    };

    return 0;

}

use std::io;

use std::sys;

@default fn main(env: *sys::Env) -> i32 {

    let args = env.args;

    for arg, i in args {

        io::printU32(i);

        io::print(": ");

        io::print(arg);

        io::print("\n");

    }

    return 0;

}

//! The Radiance Standard Library.

// TODO: The order of these module declarations matter, but they shouldn't.

// Nb: `testing` must come before all other modules so that `@test mod`

// submodules can `use std::testing` during resolution.

@test pub mod testing;

pub mod io;

pub mod collections;

pub mod lang;

pub mod sys;

pub mod debug;

pub mod arch;

pub mod fmt;

pub mod mem;

pub mod vec;

pub mod intrinsics;

// Test modules.

@test pub mod tests;

//! RISC-V instruction set architecture encodings.

pub mod rv64;

//! RV64 code generation backend.

//!

//! Generates RISC-V 64-bit machine code from IL (intermediate language).

//!

//! # Submodules

//!

//! * encode: Instruction encoding functions

//! * decode: Instruction decoding (for disassembly/printing)

//! * emit: Binary emission context and branch patching

//! * isel: Instruction selection (IL to RV64 instructions)

//! * printer: Assembly text output

pub mod encode;

pub mod decode;

pub mod emit;

pub mod isel;

pub mod printer;

@test mod tests;

use std::debug;

use std::mem;

use std::lang::il;

use std::lang::alloc;

use std::lang::gen::labels;

use std::lang::gen::regalloc;

////////////////

// Registers  //

////////////////

/// RISC-V general-purpose register.

pub record Reg { n: u8 }

pub const ZERO: Reg = { n: 0 };   /// Hard-wired zero.

pub const RA:   Reg = { n: 1 };   /// Return address.

pub const SP:   Reg = { n: 2 };   /// Stack pointer.

pub const GP:   Reg = { n: 3 };   /// Global pointer.

pub const TP:   Reg = { n: 4 };   /// Thread pointer.

pub const T0:   Reg = { n: 5 };   /// Temporary/alternate link register.

pub const T1:   Reg = { n: 6 };   /// Temporary.

pub const T2:   Reg = { n: 7 };   /// Temporary.

pub const S0:   Reg = { n: 8 };   /// Saved register/frame pointer.

pub const FP:   Reg = { n: 8 };   /// Frame pointer (alias for S0).

pub const S1:   Reg = { n: 9 };   /// Saved register.

pub const A0:   Reg = { n: 10 };  /// Function argument/return.

pub const A1:   Reg = { n: 11 };  /// Function argument/return.

pub const A2:   Reg = { n: 12 };  /// Function argument.

pub const A3:   Reg = { n: 13 };  /// Function argument.

pub const A4:   Reg = { n: 14 };  /// Function argument.

pub const A5:   Reg = { n: 15 };  /// Function argument.

pub const A6:   Reg = { n: 16 };  /// Function argument.

pub const A7:   Reg = { n: 17 };  /// Function argument.

pub const S2:   Reg = { n: 18 };  /// Saved register.

pub const S3:   Reg = { n: 19 };  /// Saved register.

pub const S4:   Reg = { n: 20 };  /// Saved register.

pub const S5:   Reg = { n: 21 };  /// Saved register.

pub const S6:   Reg = { n: 22 };  /// Saved register.

pub const S7:   Reg = { n: 23 };  /// Saved register.

pub const S8:   Reg = { n: 24 };  /// Saved register.

pub const S9:   Reg = { n: 25 };  /// Saved register.

pub const S10:  Reg = { n: 26 };  /// Saved register.

pub const S11:  Reg = { n: 27 };  /// Saved register.

pub const T3:   Reg = { n: 28 };  /// Temporary.

pub const T4:   Reg = { n: 29 };  /// Temporary.

pub const T5:   Reg = { n: 30 };  /// Temporary.

pub const T6:   Reg = { n: 31 };  /// Temporary.

/// Create a register from a number. Panics if `n > 31`.

pub fn reg(n: u8) -> Reg {

    debug::assert(n < 32);

    return Reg { n };

}

////////////////////////////

// Architecture constants //

////////////////////////////

/// Total number of general-purpose registers.

pub const NUM_REGISTERS: u8 = 32;

/// Word size in bytes (32-bit).

pub const WORD_SIZE: i32 = 4;

/// Doubleword size in bytes (64-bit).

pub const DWORD_SIZE: i32 = 8;

/// Instruction size in bytes.

pub const INSTR_SIZE: i32 = 4;

/// Stack alignment requirement in bytes.

pub const STACK_ALIGNMENT: i32 = 16;

/////////////////////////

// Codegen Allocation  //

/////////////////////////

/// Argument registers for function calls.

pub const ARG_REGS: [Reg; 8] = [A0, A1, A2, A3, A4, A5, A6, A7];

/// Scratch register for code gen. Never allocated to user values.

pub const SCRATCH1: Reg = { n: 30 };

/// Second scratch register for operations needing two temporaries.

pub const SCRATCH2: Reg = { n: 31 };

/// Dedicated scratch for address offset adjustment. Never allocated to user

/// values and never used for operand materialization, so it can never

/// conflict with `rd`, `rs`, or `base` in load/store helpers.

pub const ADDR_SCRATCH: Reg = { n: 29 };

/// Callee-saved registers that need save/restore if used.

pub const CALLEE_SAVED: [Reg; 11] = [S1, S2, S3, S4, S5, S6, S7, S8, S9, S10, S11];

/// Maximum 12-bit signed immediate value.

pub const MAX_IMM: i32 = 2047;

/// Minimum 12-bit signed immediate value.

pub const MIN_IMM: i32 = -2048;

/// Allocatable register numbers for register allocation.

const ALLOCATABLE_REGS: [u8; 23] = [

    5, 6, 7, 28,                                // T0-T3

    10, 11, 12, 13, 14, 15, 16, 17,             // A0-A7

    9, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27,  // S1-S11

];

/// Argument register numbers for register allocation.

const ARG_REG_NUMS: [u8; 8] = [10, 11, 12, 13, 14, 15, 16, 17]; // A0-A7

/// Callee-saved register numbers for frame layout.

const CALLEE_SAVED_NUMS: [u8; 11] = [9, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27]; // S1-S11

/// Get target configuration for register allocation.

// TODO: This should be a constant variable.

pub fn targetConfig() -> regalloc::TargetConfig {

    return regalloc::TargetConfig {

        // TODO: Use inline slice when we move to self-hosted compiler.

        allocatable: &ALLOCATABLE_REGS[..],

        argRegs: &ARG_REG_NUMS[..],

        calleeSaved: &CALLEE_SAVED_NUMS[..],

        slotSize: DWORD_SIZE,

    };

}

///////////////////////