Guide

An introduction to kola for a working developer, whatever language you come from. You do not need to know Rust: where kola borrows an idea from it, the chapter explains the idea from scratch, and where kola departs from it, the syntax shows the difference. If a chapter leaves you confused, that is a bug in the chapter, and we would like to hear about it.

Start by building the compiler in Quick start. From there you can take either of two routes. Hands-on is an eight-step ladder of small programs, each with an exercise that breaks it on purpose. The chapters below cover the same ideas systematically and in more depth. Doing the ladder first and then the chapters works best. Every example on these pages passes kola check, so you can copy it and run it. If you meet an unfamiliar word, look it up in the glossary.

The first eight chapters are the core and build on each other in order. The rest stand alone and can be read in any order once you know the core, with one exception: read Hardware before The machine, which takes granted windows as given.

Basics: values, functions, data: main and its signature, integer types and literals, the three conversions, arithmetic that traps instead of wrapping, strings, loops, structs, match, tuples and the first tests.
Memory: regions and references: arenas instead of malloc/free, a garbage collector or a borrow checker; why this is safe and what it costs; region, the two kinds of reference, Vec and Pool.
Resources and linearity: values that cannot be lost, which turns "forgot to close it" into a compile error.
Effects and capabilities: the signature as an audit of what a function can do and what it can reach; memory budgets; determinism.
Contracts, traps, and tests: the two kinds of error, req and ens, checks that cannot be turned off, and what a trap actually stops.
Modules, the standard library, and fn references: use, a tour of std, and polymorphism without closures or traits.
Constant time (ct): why code handling a secret key must take the same time whatever the key is, so that an attacker cannot learn it by measuring; why that means no branching or indexing on it; ct fn, the select idiom and pub parameters.
Threads and channels: running code in parallel with no shared mutable memory, only moved values; spawn, Thread[R] and join; channels with Tx[T] and Rx[T]; a seeded scheduler for deterministic tests.
Generics: everything in square brackets: type parameters, the T: data bound, region parameters, const parameters [const N: usize], generic impl blocks, and how the compiler makes a specialized copy of a generic function for each type it is used with.
Filesystem: the cwd-rooted Fs and granted roots, File as a linear handle, atomic replacement, stat, and crash simulation from a seed.
Command-line programs: arguments, the environment, standard streams and the terminal; running a granted external binary with sys.proc; and the difference between an eight-bit exit code and a trap.
Networking: Dial and Listen as separate capabilities, linear sockets, the poller, attenuating a Dial for a worker, sys.ping, and a deterministic network simulator.
Time: the Clock capability's three readings (now, monotonic; now_wall_ns, since the Unix epoch; now_boot, which also counts suspend), sleeping, deadlines, civil dates and ISO 8601 in std::time, and the simulated clock.
Desktop windows: opening a window and drawing into its frame of pixels, keyboard and mouse events, testing a window program against a simulated window with no screen, and a tray icon with a menu, on Linux, Windows and macOS.
Serialization and encodings: reading wire bytes without copying them, and the std encoders for bytes, base64, DER, JSON, XML and PEM.
Cryptography in std: the std/crypto tree (SHA-2 and SHA-3, HMAC and HKDF, AES-GCM, ChaCha20-Poly1305, X25519, Ed25519, P-256, P-384, RSA, ML-KEM, ML-DSA, X.509); the ct, untrusted and Secret[T] disciplines; and Entropy for every value an attacker must not be able to guess.
SIMD: instructions that process several numbers at once, in two families of vector lanes with opposite rules. The ct lanes (u32x4, u32x8) allow only bitwise, wrapping and constant-shift operations; the media lanes (u8x16, i16x8, i32x4 and their AVX2 twins) offer saturating arithmetic and the operations codecs need.
The MCP layer: kola mcp, the compiler as a server that an editor or an agent queries instead of searching the source tree.
Packages (kola.pack): the manifest, the [caps] budget a reviewer reads, kola audit, dependencies and publishing.
Hardware: granted windows and typed device access: talking to hardware through memory-mapped registers (MMIO, where reading or writing certain addresses talks to a device instead of RAM); sys.mmio handing out MMIO, RAM and port windows by name, with every access bounds- and alignment-checked; read-only windows and seqlock snapshots; and the device model that stands in for hardware in tests.
The machine: Cpu, ordering, and atomics: the hw effect and why it is separate from io; sys.cpu for interrupt state, halting and privileged registers; atomic operations on a shared slice; and how to publish data to another CPU core so that it sees the writes in the right order.
Bare metal: code that runs without an operating system, and device files under one; Dev and Device for userspace character devices, with a model that replaces the device in a hosted run; layout_assert[T](size, align); kola build --freestanding and the hooks a platform supplies.
Embedding kola in a C program: the generated .kh header and how kola types map to C; pub as the linkage control; the wrapper that enforces req on every exported function; and why calls go only from C into kola.
Region leaks: the one way memory can pile up under regions, an allocation made on every pass of a loop into a region the loop did not open; what kola report leaks finds and what it cannot see; and the [leaks] budget in a manifest.

Beyond the chapters: Under the hood describes the interpreter, the backends, the targets and the boundary with C. Security explains how kola makes a program's security surface a finite list. IR-0 describes the verified intermediate representation that every compiled backend reads, and the one place where the compiler may decide that a check is unnecessary. The golden/ directory of the repository holds normative examples.