klio

An experimental Kotlin interpreter written in Zig.

klio reads a .kt source file (or a set of files), lowers it to a register-based intermediate representation, and executes that IR directly. There is no JVM, no Kotlin/Native, and no separate compilation step — the same hand-written Zig pipeline that parses your code also runs it.

Highlights

• Drop-in for interpreting Kotlin. klio targets Kotlin 2.4.20 with essentially full language coverage: for running Kotlin programs it is a drop-in replacement for kotlinc, verified by diffing stdout byte-for-byte against the real compiler.
• IR-based execution. Source is lowered by the ir module into a register IR that the interp_ir Vm runs. The Vm never walks an AST.
• Tiered JIT and a tracing GC. Hot loops and functions compile to native code (x86-64 and AArch64 backends); the heap is managed by a precise mark-sweep collector. One --opt profile controls both.
• Pack-based libraries. The stdlib ships as a versioned .klio-pack embedded into the binary; the same format hosts kotlinx-coroutines, kotlinx-serialization, ktor, the Compose runtime, and third-party libraries.
• Declarative native bindings. A pack's klio.toml lists FQN → host_symbol pairs. Zig modules register host symbols once; the loader joins them at install time and a native function shadows the matching Kotlin body at dispatch.
• Single binary. zig build produces a ./zig-out/bin/klio command that runs files, runs tests, type-checks, and manages packs — and klio bundle packages a program into a self-contained executable of its own.

Where to start

• Install klio and run your first program.
• Write and run a hello world.
• Take the CLI tour for the full command surface.
• Test your Kotlin with klio test and kotlin.test.
• Ship a program as one self-contained executable with klio bundle.

Design records

• Design records — the plan-side architecture summary, the coroutine model, GC, JIT, diagnostics, benchmarks, stdlib and intrinsics records, and the analysis/ notes that document load-bearing decisions.

Architecture

• Pipeline overview — where each Kotlin construct is handled, from lexer to Vm.
• The Vm — lowering, values, dispatch, coroutines.
• Performance — the --opt profiles, the JIT tiers and backends, and the garbage collector.
• Standard library — how upstream Kotlin source plus native intrinsics become the embedded stdlib pack.
• Concurrency — real threads, dispatchers, and the coroutine engine.
• Memory model — the normative rules, each with an executable litmus program.
• Diagnostics — codes, wording rules, output formats.

Packs

• What is a pack?
• Pack format
• Using packs — installing, feature flags, troubleshooting.
• Authoring a pack
• Native bindings
• Shipped packs: kotlinx.atomicfu, kotlinx.io, kotlinx.datetime, kotlinx.coroutines, kotlinx.serialization, io.ktor, androidx.compose.runtime.

Development

• Workspace layout
• Testing and verification — the unit / integration split, the parity sweep, the stdlib commonTest gate, and the fast iteration playbook.
• Contributing

Running plan documents and design records live under plans/ in the repository (GC, JIT, coroutine model, resolution work, and the rest); they are working documents, not user documentation.

Status

Experimental, tracking Kotlin 2.4.20. Two harnesses hold the drop-in claim up: the parity sweep runs every corpus program (532) and example (142) through both kotlinc and klio and diffs stdout byte-for-byte, and the upstream stdlib's own commonTest suite (117 files, ~2,150 tests) runs directly under the interpreter at 100% per-file pass rate. Kotlin 2.4's new language features (explicit backing fields, the @all use-site target, annotation use-site defaulting, context parameters) are in progress.