Compiler Internals

The current compiler story is self-hosted-first. The repo still contains Rust-side infrastructure, but the active implementation map a contributor should learn now lives primarily under self-hosted/, with the checked souc artifact acting as the executable front door for users and for most docs verification.

Current architecture map

• self-hosted/lexer/ and self-hosted/parser/ handle tokenization and syntax.
• self-hosted/resolve/ handles imports, modules, and package resolution work.
• self-hosted/check/ is the semantic heart of the compiler, covering types, effects, epistemics, units, ownership, patterns, traits, refinements, and more.
• self-hosted/hlir/ and self-hosted/ir/ cover lowering and optimization-oriented intermediate representations.
• self-hosted/native/, self-hosted/wasm/, self-hosted/gpu/, self-hosted/llvm/, and self-hosted/lsp/ cover backend and tooling work.

The artifact-facing view

export SOUC_BIN="$(pwd)/bin/souc"
"$SOUC_BIN" info
"$SOUC_BIN" --help

How Rust still fits in

• The former Rust compiler crate no longer exists; the compiler source is self-hosted/ (Sounio), and the frontend lives in self-hosted/lexer/ and self-hosted/parser/.
• The checked artifact is built from self-hosted/ by the bootstrap chain (make build), not by Cargo.
• For docs, the safest contributor narrative is: use the artifact for current behavior, and use self-hosted/ as the primary implementation map.

How to navigate the codebase

• Start at self-hosted/compiler/main.sio for the driver-facing view.
• Then move outward to the dedicated subsystem directories instead of relying only on the thin wrapper files in self-hosted/compiler/.
• Use docs/codebase_overview.md and the implementation docs as orientation aids, but confirm path-level claims against the actual tree.

Troubleshooting

• Stack Overflow (Madaros Compiler): The recursive expression compiler can generate extremely large stack frames (e.g., ~4.85 MB per frame) when deeply nested. This was recently fixed in the live codegen logic by aligning the dynamic frame sizing to register counts (align16((*func).reg_count*8)). However, if you experience a SIGSEGV or segfault when compiling large functions with nested boolean operations, ensure you increase your stack size limit: ulimit -s unlimited.