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

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