Section 21B: AOT Compilation

Proposal: proposals/approved/aot-compilation-proposal.md Depends on: Section 21A (LLVM Backend - JIT working)

21B.1 Target Configuration

Supported targets (initial):

Target	Description
`x86_64-unknown-linux-gnu`	64-bit Linux (glibc)
`x86_64-unknown-linux-musl`	64-bit Linux (musl, static)
`x86_64-apple-darwin`	64-bit macOS (Intel)
`aarch64-apple-darwin`	64-bit macOS (Apple Silicon)
`x86_64-pc-windows-msvc`	64-bit Windows (MSVC)
`x86_64-pc-windows-gnu`	64-bit Windows (MinGW)
`wasm32-unknown-unknown`	WebAssembly (standalone)
`wasm32-wasi`	WebAssembly (WASI)

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (21B.1) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-21B.1 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 21B.1: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

21B.2 Object File Emission

21B.3 Debug Information

21B.4 Optimization Pipeline

21B.5 Linking

21B.6 Incremental Compilation

21B.7 WebAssembly Backend

21B.8 CLI Integration

21B.8.5 Multi-File Compilation

Proposal: proposals/approved/multi-file-aot-proposal.md

Enable AOT compilation of Ori programs with imports. Currently, ori build produces broken binaries when the source uses use statements.

21B.8.5.1 Dependency Graph Infrastructure

21B.8.5.2 Per-Module Compilation

Implement: Per-module compilation in build_file_multi() (verified 2026-03-29)
- Compile single module to object file
- Use module-qualified name mangling (_ori_<module>$<function>)
- Generate declare for imported symbols via declare_external_fn_mangled()
- Rust Tests: ori_llvm/src/declare.rs
Implement: Update ori demangle for module paths
- Parse _ori_helper$my_assert → helper.@my_assert
- Handle nested paths (_ori_http$client$connect → http/client.@connect)
- Rust Tests: oric/src/commands/demangle.rs (9 tests)

21B.8.5.3 Linking Integration

Implement: Multi-file linking in build_file_multi()
- Collect all object files from dependency graph
- Pass to existing linker infrastructure via link_and_finish()
- Handle stdlib library paths via ORI_STDLIB
- Rust Tests: Covered by existing linker tests

21B.8.5.4 Cache Integration

Implement: Wire incremental cache (21B.6) to multi-file builds
- Check cache for each module before compilation
- Store module hash including import signatures
- Invalidate dependents when module changes
- Rust Tests: ori_llvm/src/aot/multi_file.rs

21B.8.5.5 Error Handling

Implement: Multi-file error reporting
- E5004: Import target not found (searched paths in note)
- E5005: Imported item not found (with “did you mean?” suggestions)
- E5006: Imported item is private (suggest :: prefix)
- Rust Tests: ori_llvm/src/aot/multi_file.rs

21B.8.5.6 Testing

21B.9 Error Handling

21B.10 End-to-End Pipeline Tests

Proposed test infrastructure (formal AotTestExecutor, --backend=aot) is not started. However, 1977 AOT integration tests exercise the full parse-typeck-codegen-link-execute pipeline. diagnostics/dual-exec-verify.sh exists for interpreter vs AOT comparison. (verified 2026-03-29)

Proposal: proposals/approved/aot-test-backend-proposal.md

21B.10.1 AOT Test Backend Infrastructure

21B.10.2 End-to-End Test Scenarios

21B.11 Performance & Stress Tests

STALE STATUS corrected from not-started. compiler/ori_llvm/tests/aot/stress.rs has 34 tests; memory_stress.rs also exists. (verified 2026-03-29)

21B.12 Platform-Specific Tests

Linux (MEDIUM priority)

Reference: Rust tests/run-make/, Zig test/link/

macOS (MEDIUM priority)

Reference: Rust macOS-specific run-make tests

Test: macOS-specific linking
- Framework linking (-framework)
- Code signing requirements
- dSYM bundle structure verification
- Deployment target (-mmacosx-version-min)
- SDK version specification
- Universal binary (fat binary) support
- @rpath, @loader_path, @executable_path
- Two-level namespace vs flat namespace

Windows (MEDIUM priority)

Reference: Rust Windows run-make tests

21B.13 ABI & FFI Tests

ABI Compliance (LOW priority)

Reference: Rust ABI tests, Zig calling convention tests

FFI Type Verification (LOW priority)

Reference: Rust FFI tests

21B.14 Architecture-Specific Codegen

LOW priority - Reference: Rust codegen tests, Zig behavior tests

21B.15 Testing Infrastructure

Required utilities for comprehensive testing

21B.16 Section Completion Checklist

Target Configuration (21B.1): (verified 2026-03-29)

Target triple parsing and validation
Data layout configuration
CPU feature detection
Native target auto-detection

Object Emission (21B.2): (verified 2026-03-29 — core emission done, verification tests not started)

ELF, Mach-O, COFF, WASM output
Symbol mangling scheme
ori demangle command (with tests)
Object file verification tests (10 scenarios)
Symbol management tests (9 scenarios)

Debug Information (21B.3): (verified 2026-03-29 — implementation done, 10 tests; verification tests not started)

Optimization (21B.4): (verified 2026-03-29 — implementation done; pass manager has ZERO unit tests)

O0-O3, Os, Oz levels
Thin LTO and Full LTO
Pass manager configuration — WEAK TESTS (0 direct unit tests, 827 lines untested)
LTO advanced tests (7 scenarios)
Code model tests (8 scenarios)

Linking (21B.5): (verified 2026-03-29 — core linking done, 69 tests)

System linker driver (cc/clang/link.exe)
LLD support
Runtime library (libori_rt)
Static and dynamic linking
Runtime library discovery (binary-relative, like rustc sysroot)
Linker error handling tests (8 scenarios)
Linker feature tests (9 scenarios)

Incremental (21B.6): (verified 2026-03-29 — infrastructure done with 77 tests; GAP-1 CRITICAL: not wired to ori build)

Source hashing
Dependency tracking
Cache management
Parallel compilation
Wire up cache to ori build command (blocks 21B.8 incremental test) — GAP-1 CRITICAL
Incremental advanced tests (8 scenarios)

WebAssembly (21B.7): (verified 2026-03-29 — substantially implemented, 73 tests)

CLI (21B.8): (verified 2026-03-29 — all commands implemented, 125 tests total)

ori build command (with tests)
ori targets command (with tests)
ori target add/remove commands (with tests)
ori demangle command (with tests)
ori run --compile mode (with tests)
CLI integration tests (42 end-to-end tests)
Build incremental test (blocked on 21B.6 integration)

Multi-File Compilation (21B.8.5): (verified 2026-03-29 — infrastructure done, 15 tests)

Dependency graph infrastructure
Per-module compilation with name mangling
Linking integration
ori demangle Ori-style output (module.@function)
Cache integration (reuse 21B.6)
Error handling (E5004-E5006)
Multi-file tests (13 scenarios)

Error Handling (21B.9):

Linker error reporting
Target error reporting
Object generation error reporting
Error handling tests (13 scenarios)
Error diagnostics tests (7 scenarios)

End-to-End Pipeline (21B.10): (verified 2026-03-29 — proposed infrastructure not started; 1977 AOT integration tests cover pipeline functionally)

End-to-end execution tests (12 scenarios)

Performance & Stress (21B.11): (verified 2026-03-29 — 34 stress tests exist in stress.rs + memory_stress.rs)

Performance benchmark tests (8 scenarios)

Platform-Specific (21B.12):

Linux-specific tests (8 scenarios)
macOS-specific tests (8 scenarios)
Windows-specific tests (9 scenarios)

ABI & FFI (21B.13):

ABI compliance tests (8 scenarios)
FFI type verification tests (7 scenarios)

Architecture Codegen (21B.14):

Architecture codegen tests (7 scenarios)

Testing Infrastructure (21B.15):

LLVM test utilities (6 tools)
Test infrastructure (3 features)
/tpr-review passed — independent Codex review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — implementation hygiene review clean (phase boundaries, SSOT, algorithmic DRY, naming). MUST run AFTER /tpr-review is clean.
/improve-tooling retrospective completed — MANDATORY at section close, after both reviews are clean. Reflect on the section’s debugging journey (which diagnostics/ scripts you ran, which command sequences you repeated, where you added ad-hoc dbg!/tracing calls, where output was hard to interpret) and identify any tool/log/diagnostic improvement that would have made this section materially easier OR that would help the next section touching this area. Implement every accepted improvement NOW (zero deferral) and commit each via SEPARATE /commit-push. The retrospective is mandatory even when nothing felt painful — that is exactly when blind spots accumulate. See .claude/skills/improve-tooling/SKILL.md “Retrospective Mode” for the full protocol.

Test Coverage Summary: (verified 2026-03-29)

Priority	Category	Plan Scenarios	Actual Tests	Status
CRITICAL	CLI Integration (21B.8)	12	125	[done]
CRITICAL	Multi-File Compilation (21B.8.5)	13	15	[partial]
CRITICAL	Error Handling (21B.9)	20	0	[todo]
CRITICAL	End-to-End Pipeline (21B.10)	12	0 (proposed infra)	[todo]
CRITICAL	Performance/Stress (21B.11)	8	34	[partial]
HIGH	Linker Tests (21B.5)	17	69	[done]
HIGH	Object File Tests (21B.2)	19	0	[todo]
MEDIUM	Platform-Specific (21B.12)	25	0	[todo]
MEDIUM	WASM Advanced (21B.7)	10	0 (73 core)	[todo]
MEDIUM	LTO Advanced (21B.4)	15	0 (17 core)	[todo]
MEDIUM	Incremental (21B.6)	8	0 (77 infra)	[todo]
MEDIUM	Debug Info (21B.3)	9	0 (10 core)	[todo]
LOW	ABI/FFI (21B.13)	15	0	[todo]
LOW	Architecture (21B.14)	7	0	[todo]
Total		~190 scenarios	400+ actual

Exit Criteria: Native executables and WASM modules can be generated from Ori source with full debug support, optimization levels, incremental compilation, and multi-file import support. All test scenarios pass with comprehensive coverage.

/tpr-review passed — independent review found no critical or major issues (or all findings triaged)
/impl-hygiene-review passed — hygiene review clean. MUST run AFTER /tpr-review is clean.
Subsection close-out (21B.16) — MANDATORY before starting the next subsection. Run /improve-tooling retrospectively on THIS subsection’s debugging journey (per .claude/skills/improve-tooling/SKILL.md “Per-Subsection Workflow”): which diagnostics/ scripts you ran, where you added dbg!/tracing calls, where output was hard to interpret, where test failures gave unhelpful messages, where you ran the same command sequence repeatedly. Forward-look: what tool/log/diagnostic would shorten the next regression in this code path by 10 minutes? Implement improvements NOW (zero deferral) and commit each via SEPARATE /commit-push using a valid conventional-commit type (build(diagnostics): ... — surfaced by section-21B.16 retrospective — build/test/chore/ci/docs are valid; tools(...) is rejected by the lefthook commit-msg hook). Mandatory even when nothing felt painful. If genuinely no gaps, document briefly: “Retrospective 21B.16: no tooling gaps”. Update this subsection’s status in section frontmatter to complete.
/sync-claude section-close doc sync — verify Claude artifacts across all section commits. Map changed crates to rules files, check CLAUDE.md, canon.md. Fix drift NOW.
Repo hygiene check — run diagnostics/repo-hygiene.sh --check and clean any detected temp files.

LLVM Version Requirement

Required: LLVM 21 or later

Rationale:

Best WASM support with Component Model preview
Newest pass manager (default since LLVM 14)
Improved debug info generation
No legacy compatibility burden

Running Tests

# Run all AOT tests (1977 tests)
cargo test -p ori_llvm

# Run AOT-specific tests
cargo test -p ori_llvm --lib aot

# Run WASM-specific tests
cargo test -p ori_llvm --lib wasm

# Build and run an executable
ori build src/main.ori -o myapp && ./myapp

# Build for WASM
ori build --wasm src/main.ori -o myapp.wasm