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

Key packages

Package

Role

pkg/codegen

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).

pkg/cli

All CLI commands, drivers and test harnesses.

pkg/ir/ssa

Typed SSA IR with dominance tree, liveness, optimization pipeline (Mem2Reg, FoldConst, CSE, DCE, LICM) and verifier.

pkg/ir/hir

High-level IR with typed expression/statement/type nodes.

pkg/parser

AST model (ast.go) and recursive-descent parser.

pkg/lexer

Tokenizer with the const keyword (Phase 112) and nested block comments.

pkg/sema

Semantic analysis — resolve.go (exports, const tracking, borrow model), npu_check.go.

pkg/backend/cpu

Reference CPU backend (correctness oracle).

pkg/backend/gpu

GPU/WGSL backend (no language surface yet).

pkg/npu/*

NPU vendor adapters (intel/qualcomm/apple/amd/arm) and quantum backend abstraction.

pkg/wasm

Karkain-owned wasm32-wasi backend (WASM binary v1 emitter, runtime glue).

pkg/compiler

Incremental compilation cache (content-addressed, interface-hashed).

pkg/target

Target-triple model, feature flags, supported-target matrix (Phase 111).

pkg/pm

Package manager — resolver, lockfile, local fetch.

pkg/source

Source file line-index model (used by CLI and LSP).

pkg/lsp

Language Server Protocol implementation.

pkg/math

Math IR (internal, no language surface).

pkg/tensor

Tensor IR (internal, no language surface).

pkg/testing

Test-driver utilities.

pkg/jit

JIT engine boundary (no user-facing surface).

pkg/bootstrap

Bootstrap pipeline (KARKAIN_ENGINE=go pinned).

pkg/diagnostics

Structured diagnostic model.

pkg/module

Module graph and std.* resolution.

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 debug and karkain prof.

  • Self-hosted kcc — the default engine for check/build/run/ test on 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.