Compiler Internals

A guided map of the `souc` compiler: frontend, type checking, IRs, and backends.

Compiler Internals

This section documents how the Sounio compiler (souc) is organized and where to look in the codebase.

For language behavior, treat tests/ as ground truth. For the formal direction of the language, see the spec (which may be aspirational in places).

High-Level Pipeline

.sio source
  -> lexer (tokens + spans)
  -> parser (AST)
  -> module loading + name resolution
  -> type checking (types + effects + units + ownership)
  -> IR lowering / optimization (HIR -> HLIR -> MIR)
  -> code generation (Cranelift / native / LLVM / GPU)
  -> artifacts (JIT, object files, GPU IR, diagnostics)

Project Snapshot (Approx.)

MetricValue
Implementation languageRust (edition 2024)
Compiler cratecrates/souc/
Stdlib locationstdlib/
Core backendsCranelift, native, LLVM (optional), GPU

Key Directories (Where Things Live)

  • crates/souc/src/lexer/ — tokenization (Logos-based)
  • crates/souc/src/parser/ — recursive descent parser + Pratt expression parsing
  • crates/souc/src/ast/ — AST definitions (syntax-level nodes)
  • crates/souc/src/resolve/ — module tree + import resolution
  • crates/souc/src/check/ — type checker (effects/units/ownership integration)
  • crates/souc/src/hir/, crates/souc/src/hlir/, crates/souc/src/mir/ — typed IRs and optimizations
  • crates/souc/src/codegen/ — lowering and backend-specific code generation
  • crates/souc/src/backend/ — runtime glue (native, effects dispatch, GPU bridge)

Running the Compiler (Local Dev)

# Build `souc`
cargo build -p souc

# Type-check a program
./target/debug/souc check path/to/file.sio

Start Here

  • docs/compiler/KNOWN_LIMITATIONS.md — dependency-gated behavior and feature flags
  • spec/LANGUAGE_SPECIFICATION.md — formal spec (may run ahead of the compiler)
  • tests/ — runnable fixtures and regression coverage