Karkain Language Guide
Karkain is a statically typed language compiled to C23. Programs are
written in .kark files and executed through one of two engines:
Go front end — the reference compiler (lex → parse → sema → C codegen → gcc).
Self-hosted kcc engine — the primary engine for
check/build/run/test(src/compiler/*.kark→ C23 → native executable).
Future road-map targets heterogeneous computing (CPU, GPU via WGSL, NPU via vendor adapters), but the current surface is single-threaded native code with opt-in concurrency primitives (Phase 107).
Contents
How to read this guide
The chapters are ordered so that each one depends only on the chapters above it, so a new programmer can read them straight through:
fundamentals lexical structure, literals, first program shape
types int / float64 / bool / string, array, map
variables let, var, inference, shadowing
constants compile-time constants
control-flow if / while / for / for-in / match / break / continue
functions parameters, return types, the record idiom
structs records
enums tagged unions
strings UTF-8 strings and slicing
collections arrays and maps
modules imports and project layout
errors Result / Option, `?` propagation, runtime errors
memory-model ownership, borrowing, references
concurrency channels, actors, tasks
control-flow deliberately precedes functions: every construct in it can
be read without a function around it, and functions then has control flow
already in hand. strings and collections sit with structs and
enums because they are the remaining data structures; errors follows
modules because it is where Result/Option and ? become usable
end to end.
This guide teaches the language. For the precise normative definition see
Stable API Snapshot (1.2.0) and SPEC.md at the repository root; for how the
compiler and runtime are built see Compiler Internals.
Karkain reference
Getting Started — install, first project, workspace
Standard Library — the shipped standard library
Karkain by Example — the runnable example corpus
Tools —
karkainCLI commandsTargets — build targets and accelerators
Status — compatibility, scope and release status
Development — contributing and release process