Architecture
Karkain is a statically typed systems programming language with a
self-hosted compiler and a two-engine pipeline: a Go front end (the
reference compiler) and the self-hosted kcc engine. This page describes
the repository layout, the key packages and how they relate.
Repository top-level
cmd/karkain/main.go # CLI entry point and command dispatch
pkg/* # 23 Go packages (the compiler and toolchain)
src/compiler/*.kark # self-hosted kcc compiler (8 source files)
runtime/freestanding/ # libc-free arena allocator + platform abstraction
runtime/core/ # libc-free heap, tagged Value, native strings/arrays
runtime/concurrency/ # work-stealing scheduler, channels, actors (C runtime)
stdlib/ # 11 stdlib modules (6 importable, 5 boundary)
examples/ # language_foundation, algorithms, concurrency, wasm, ...
conformance/ # 11 test files, 59 test functions
docs/ # official documentation (Sphinx RST)
scripts/ # build and utility scripts
The CLI
cmd/karkain/main.go is the single binary: karkain build, run,
test, check, fmt, lint, debug, prof, target,
pkg, lsp and more are all dispatched from one main function.
The command surface is documented in Command-Line Interface.
The 23 Go packages
Package |
Role |
|---|---|
|
C emitter — produces C23 source from Karkain AST/IR, with the profiling/trace/SIMD/target-header emitters embedded. The dominant codegen package (emits most of the generated C). |
|
All CLI commands, drivers and test harnesses. |
|
Typed SSA IR with dominance tree, liveness, optimization pipeline (Mem2Reg, FoldConst, CSE, DCE, LICM) and verifier. |
|
High-level IR with typed expression/statement/type nodes. |
|
AST model ( |
|
Tokenizer with the |
|
Semantic analysis — |
|
Reference CPU backend (correctness oracle). |
|
GPU/WGSL backend (no language surface yet). |
|
NPU vendor adapters (intel/qualcomm/apple/amd/arm) and quantum backend abstraction. |
|
Karkain-owned |
|
Incremental compilation cache (content-addressed, interface-hashed). |
|
Target-triple model, feature flags, supported-target matrix (Phase 111). |
|
Package manager — resolver, lockfile, local fetch. |
|
Source file line-index model (used by CLI and LSP). |
|
Language Server Protocol implementation. |
|
Math IR (internal, no language surface). |
|
Tensor IR (internal, no language surface). |
|
Test-driver utilities. |
|
JIT engine boundary (no user-facing surface). |
|
Bootstrap pipeline ( |
|
Structured diagnostic model. |
|
Module graph and |
The self-hosted compiler
src/compiler/ contains 8 .kark source files:
main.kark ast.kark parser.kark sema.kark
checker.kark codegen.kark lexer.kark atypes.kark
The self-hosted compiler is the primary engine for check / build /
run / test (Phase 95–99). It is compiled via bootstrap (Go
codegen → C23 → native executable) and produces byte-identical C output to
the Go front end on the same source files.
src/compiler/codegen.kark mirrors the C emission of
pkg/codegen/codegen.go; src/compiler/checker.kark mirrors
pkg/sema/resolve.go. Language surface changes need changes in both
trees.
The transitional architecture
Karkain is in a transitional state:
Go front end — handles all exotic backends (SIMD, profiling, tracing, WASM, native linking), is the reference for runtime behavior, and is the only engine that supports concurrency,
karkain debugandkarkain prof.Self-hosted kcc — the default engine for
check/build/run/teston ordinary single-threaded programs; kcc parity for concurrency and some advanced surfaces is deferred.
pkg/codegen is the largest package because it handles most of the C
emission. pkg/cli is the second-largest because it wires every CLI
command and hosts the test harnesses. The self-hosted compiler
(src/compiler/) mirrors the Go packages but does not yet cover SIMD,
profiling, tracing, WASM or native-linking codegen.
The runtime boundary
runtime/freestanding/ # arena allocator, platform abstraction (no libc)
runtime/core/ # heap, Value, NativeString, NativeArray (no libc)
runtime/concurrency/ # C scheduler, channels, actors (no libc)
The freestanding and core layers compile with -ffreestanding -nostdlib.
The concurrency runtime is embedded into generated C via
pkg/codegen/conc_runtime.go.
See also
Overall Architecture — the compiler internals in depth. The Self-Hosted kcc Engine — the self-hosted engine specifically. Command-Line Interface — every CLI command and exit code.