Architecture

Architecture

Sun is a compiled language with an LLVM 20 backend.

This page gives a high-level overview of the compiler. Two stages have dedicated deep-dives:

  • Semantic Analysis — type inference, scope resolution, generics, and capture detection
  • Code Generation — LLVM IR emission, lowering conventions, and source layout

Compilation Pipeline

Source → Lexer → Parser → AST → Manifest Processing → Merged AST → Semantic Analyzer → Borrow Checker → Codegen Visitor → LLVM IR → JIT/AOT

Pipeline Steps

  1. Lexer — Tokenize source file
  2. Parser — Build AST from tokens
  3. Manifest Processing — Extract manifest, parse additional suns, load moons
  4. AST Merging — Combine all parsed ASTs into a single merged AST
  5. Semantic Analysis — Type inference, scope resolution, capture detection
  6. Borrow Checking — Ownership and lifetime analysis
  7. Code Generation — Emit LLVM IR
  8. JIT/AOT — Execute immediately or compile to native binary

Component Overview

ComponentFilesDescription
Driverdriver/driver.h/cppOrchestrates the full pipeline: parse → analyze → codegen → execute
Lexerparsing/lexer.h, parsing/nfa.hNFA-based regex tokenizer supporting keywords, operators, literals (header-only)
Parserparsing/parser.h/cppRecursive descent parser producing AST nodes
ASTast.h, ast/*.h, src/ast/*.cppExpression/statement nodes with type annotations
Semantic Analyzersemantic_analysis/semantic_analyzer.h, src/semantic_analysis/*.cppType inference, scope analysis, closure capture detection
Borrow Checkerborrow_checker/*.h/cppRust-style ownership and borrowing analysis (WIP)
Codegen Visitorcodegen/codegen_visitor.h, src/codegen/*.cppVisitor pattern for AST-to-LLVM-IR translation
LLVM Codegencodegen/codegen.h, codegen/llvm_type_resolver.h/cppLLVM context, module, and type management
Compilerdriver/compiler.hAOT compilation: emit object files, link executables
SunJITdriver/sun_jit.hLLVM ORC-based JIT compiler for immediate execution
Moonmoon_bundling/moon.h/cpp, moon_bundling/library_cache.h/cppPrecompiled library format (.moon) and caching

Headers live under include/ and implementations under src/ in the same directory layout: support/, driver/, parsing/, ast/, semantic_analysis/, borrow_checker/, codegen/ (with abi/ and intrinsics/), serialization/, moon_bundling/, lsp/, debug/.

Semantic Analysis

The semantic analyzer turns a merely parsed program into an understood one: it makes two passes over the merged AST — a shallow declaration collection sweep, then a deep walk that stamps every expression with a resolved sun::Type. Type inference, expected-type propagation, compatibility checking, closure capture detection, and generic monomorphization all happen here.

See Semantic Analysis for the full deep-dive.

Code Generation

The codegen visitor walks the analyzed AST and emits LLVM IR, reading the types and annotations the semantic analyzer recorded. Its source is split across src/codegen/ by expression type.

See Code Generation for lowering conventions and the per-file breakdown.

Type System

The type system (types.h) includes:

  • Primitives: i8, i16, i32, i64, u8, u16, u32, u64, f32, f64, bool, void
  • Arrays: Fixed-size arrays with N-dimensional indexing
  • Functions/Lambdas: First-class function types with closure support
  • Pointers: ptr<T> owning pointers (RAII), raw_ptr<T> for C interop, static_ptr<T> for static data
  • References: ref T for borrowing without ownership transfer
  • Classes: User-defined value types with methods and fields
  • Interfaces: Contracts for polymorphism (including builtin IError; the stdlib supplies IIterator, IIterable)
  • Enums: Named integer variants with pattern matching support
  • Generics: Parameterized types with monomorphization
  • Errors: T, IError functions throw classes implementing IError as native exceptions
  • Threads: Thread<T> for OS thread handles via spawn

Execution Modes

JIT Execution

sun program.sun

Uses LLVM ORC JIT for immediate execution without producing binaries.

AOT Compilation

sun -c -o program program.sun

Emits object file via LLVM, links with system C compiler to produce native executable.

Debug Mode

sun --debug program.sun

Generates debugging artifacts in program_debug/:

  • ast.dot — GraphViz AST visualization
  • ir.ll — Full LLVM IR output
  • scope_tree.html — Semantic scope visualization

Flow Diagram

FormattingSemantic Analysis