Section 21A: LLVM Backend

Current Test Results

Test Suite	Passed	Failed	Skipped	LCFail	Total
Ori spec (evaluator)	3035	0	42	-	3077
Ori spec (LLVM backend)	1082	1	9	1985	3077
Rust unit tests (LLVM)	527	0	15	-	542

Import Resolution (Unified Pipeline)

The JIT test runner resolves imports via oric::imports::resolve_imports() and compiles imported function bodies directly into the JIT module. This uses the same declare_all / define_all path as main module functions, so most new codegen features automatically work for imported functions too.

Features that need import-aware changes

When implementing these features, ensure they also work across module boundaries:

Generic monomorphization: declare_all skips generics (sig.is_generic()). To compile assert_eq<T: Eq>(actual: int, expected: int), the monomorphization pass must collect concrete instantiation sites from the calling module and generate specialized versions of imported generic functions. This is the single largest gap — assert_eq is used in 2,472 test call sites.
Impl blocks from imported modules: Currently only top-level functions are compiled from imports. If an imported module has impl Type { @method ... }, those methods need compile_impls() processing with the imported module’s impl_sigs.
Type declarations from imported modules: register_user_types() only processes the main module’s types. Imported struct/sum type definitions need registration so the LLVM type resolver can compute their layouts.
Prelude functions: Currently skipped in JIT mode because some prelude functions (e.g., compare returning Ordering) use types the codegen can’t handle yet. Once sum type codegen (21.2) works, prelude compilation should be re-enabled.

21.1 LLVM Setup & Infrastructure

21.2 Type Lowering

21.3 Expression Codegen

21.4 Operator Trait Dispatch

21.5 Control Flow

21.6 Pattern Matching

21.7 Function Sequences & Expressions

21.8 Concurrency Patterns

Related Proposals:

21.9 Capabilities & With Pattern

Related Proposals:

21.10 Collections & Iterators

Related Proposals:

21.11 Lambda & Closure Support

21.12 Built-in Functions

21.13 FFI Support

Related Proposals:

21.14 Conditional Compilation

Related Proposals:

21.15 Memory Management (ARC)

Related Proposals:

21.16 Optimization Passes

21.16.1 Representation Optimization

Proposal: proposals/approved/representation-optimization-proposal.md

Formalize the compiler’s freedom to optimize machine representations while preserving semantic equivalence. Tier 1 and most Tier 2 optimizations are already implemented.

21.16.2 LLVM Optimization Pipeline

21.17 Runtime Support

21.18 Architecture (Reference)

The LLVM backend follows Rust’s rustc_codegen_llvm patterns:

Context Hierarchy

// Simple context - just LLVM types
pub struct SimpleCx<'ll> {
    pub llcx: &'ll Context,
    pub llmod: Module<'ll>,
    pub ptr_type: PointerType<'ll>,
    pub isize_ty: IntType<'ll>,
}

// Full context - adds Ori-specific state
pub struct CodegenCx<'ll, 'tcx> {
    pub scx: SimpleCx<'ll>,
    pub interner: &'tcx StringInterner,
    pub instances: RefCell<HashMap<Name, FunctionValue<'ll>>>,
    pub type_cache: RefCell<TypeCache<'ll>>,
}

Builder Pattern

pub struct Builder<'a, 'll, 'tcx> {
    llbuilder: &'a inkwell::builder::Builder<'ll>,
    cx: &'a CodegenCx<'ll, 'tcx>,
}

Directory Structure

ori_llvm/src/
├── lib.rs              # Crate root, re-exports
├── context.rs          # SimpleCx, CodegenCx, TypeCache
├── builder.rs          # Builder + expression compilation
├── types.rs            # Type mapping helpers
├── declare.rs          # Function declaration
├── traits.rs           # BackendTypes, BuilderMethods traits
├── module.rs           # ModuleCompiler (two-phase codegen)
├── runtime.rs          # Runtime FFI functions
├── evaluator.rs        # JIT evaluator (OwnedLLVMEvaluator)
├── operators.rs        # Binary/unary operator codegen
├── control_flow.rs     # if/else, loops, break/continue
├── matching.rs         # Pattern matching codegen
├── collections/        # Collection codegen (tuples, structs, lists)
│   ├── mod.rs
│   ├── tuples.rs
│   ├── structs.rs
│   ├── lists.rs
│   └── option_result.rs
├── functions/          # Function codegen
│   ├── mod.rs
│   ├── body.rs         # Function body compilation
│   ├── calls.rs        # Function call codegen
│   ├── lambdas.rs      # Lambda/closure codegen
│   ├── builtins.rs     # Built-in function codegen
│   ├── sequences.rs    # FunctionSeq (run, try, match)
│   └── expressions.rs  # FunctionExp (recurse, print, panic)
└── tests/              # Unit tests (206 tests)
    ├── mod.rs
    ├── arithmetic_tests.rs
    ├── collection_tests.rs
    ├── control_flow_tests.rs
    ├── function_tests.rs
    ├── matching_tests.rs
    └── ...

21.19 Section Completion Checklist

Infrastructure:

JIT compilation working
All current Ori tests pass via LLVM (1082/3077 passing, 1985 LCFail)
All Rust unit tests pass (527/527, 15 skipped)
Architecture follows Rust patterns
Unified import pipeline (imports resolved once, compiled into JIT module)
Generic monomorphization (biggest remaining gap for test coverage)
AOT compilation (see Section 21B)

Type System:

Expressions:

Control Flow:

Traits & Dispatch:

Associated functions
Operator trait dispatch
Iterator trait methods
Comparison trait methods

Concurrency:

Parallel pattern
Spawn pattern
Channels
Nursery pattern

Capabilities:

Capability tracking
With pattern provision
Default implementations

FFI:

C FFI
JavaScript FFI
Unsafe blocks

Memory:

ARC implementation
Drop trait
Destruction ordering

Optimization:

Optimization passes
Debug info generation
80+% test coverage (currently ~68%)

Verified AOT Gaps (from Section 11.1 verification, updated 2026-02-23):

Resolved:

Derive Eq struct codegen: emit_comparison_via_trait now dispatches to derived eq method for non-primitive types instead of falling through to scalar icmp
Derive Comparable struct codegen: emit_ordering_comparison now dispatches to derived compare method and checks Ordering result (0=Less, 1=Equal, 2=Greater) for </>/<=/>=
ARC enum basic drop and string-payload drop: test_arc_enum_basic_drop and test_arc_enum_with_string_payload un-ignored and passing

Open:

List mutation methods not in AOT builtin table: .push(), .first(), .last(), .is_empty(), .concat()
Map methods not in AOT builtin table: .is_empty(), .get(), .insert(), .remove(), .keys(), .values()
list[index] subscript not resolved in AOT
Closure-returning-closure type inference: let f = (n: int) -> (int) -> int = { (x: int) -> int = ... } infers () return instead of (int) -> int
Enum variant constructors not declared as LLVM functions
Generic monomorphization not in ARC pipeline
catch(expr:) not yet lowered through ARC pipeline
String interpolation produces wrong result

Cross-references to existing items:

Generic monomorphization → § 21.7 (CRITICAL — blocks 2,472+ test call sites)
Enum variant constructors → § 21.2 (blocks enums, recursive types)
catch(expr:) → § 21.5 (blocks panic recovery in AOT)
String interpolation → § 21.3

New AOT tests added (2026-02-23, 13 tests, all passing): derive_eq_struct (un-ignored), derive_eq_struct_not_equal, derive_eq_struct_with_strings, derive_comparable_struct (4 comparisons: <, >, <=, >=), panic_basic, option_unwrap_some, result_unwrap_ok, struct_with_list_and_string, nested_struct_with_strings, for_yield_with_filter, for_yield_transform

New AOT test files added (2026-02-23, Section 11.1 verification — 5 files, 117 tests total):

error_handling.rs — 21 tests (21 pass, 0 ignore): Result/Option basics, ? operator, chaining, deep chains
higher_order.rs — 27 tests (23 pass, 4 ignore): HOF apply, composition, closures with captures, nested closures, fold
tuples.rs — 29 tests (23 pass, 6 ignore): construction, destructuring, field access, as param/return, nested, strings, closures
structs.rs — 29 tests (28 pass, 1 ignore): construction, string fields, update syntax, nested, as param/return, closures, derived Eq
recursion.rs — 22 tests (22 pass, 0 ignore): factorial, fibonacci, tail-recursive, mutual, with Result/Option/match, depth tests

Total AOT test counts (2026-02-23): 850 passed, 0 failed, 70 ignored

Exit Criteria: Feature parity with evaluator for all language constructs

Running Tests

# Build Docker container (first time only)
./docker/llvm/build.sh

# Run all Ori tests via LLVM
./docker/llvm/run.sh ori test

# Run spec tests only
./docker/llvm/run.sh ori test tests/spec

# Run Rust unit tests
./docker/llvm/run.sh cargo test -p ori_llvm --lib

# Run with debug output
ORI_DEBUG_LLVM=1 ./docker/llvm/run.sh ori test tests/spec/types/primitives.ori