How Irij Works
Design decisions, code structure, and the trade-offs behind each subsystem. Rendered inline from the Irij repo's docs/internals/ directory.
How Irij Works — single-page overview →
The whole under-the-hood story on one page: lexing, AST, bytecode emission, state-machine effects, hot-redef, specs, and concurrency. Start here, then dive into the topic pages below.
Pipeline
Source → AST → bytecode. The single execution model and multi-pass emission.
Parser
ANTLR4 grammar + indent rewriter. Lexer quirks and reserved-word traps.
AST
Sealed-interface hierarchies for Decl/Stmt/Expr/Pattern. Why records.
Bytecode Compiler
ClassEmitter + focused emitter modules + ASM. Method shape, variable resolution, indirection.
Effects
State-machine lowering. Continuations, trampoline, lifted locals, handler state.
Tail-Call Optimization
Self-TCO via GOTO + arg rebind. Mutual TCO trade-offs.
Hot Redef
invokedynamic + MutableCallSite. The --direct-linking deploy mode.
Specs
Runtime predicates, contracts, blame tracking.
Modules
mod/use/pub. Inlining, alias rewriting, blame envelopes.
Versioning
Commit-count releases (MAJOR.MINOR.count), publish guards, dep resolution.
Packaging
Seeds, the irij.toml manifest, irij publish, registry storage.
Concurrency
Virtual threads, structured concurrency, cross-mode dispatch.
JVM Capability
Why all Java interop requires ::: JVM.
Capabilities
cap decls — bridging effect ops to host (Java) providers.
Stdlib
What lives in Java vs Irij. One implementation per builtin.
nREPL
Protocol, sessions, eval vs eval-bytecode.
LSP
irij lsp — editor integration, capabilities.
Glossary
Terms used throughout these docs.