Quick start

This page takes a small kola program from source to a checked, tested executable.

Build the compiler

The compiler is written in Rust and needs only a Rust toolchain. Build the kola-cli package; the kola crate on its own is a library.

git clone ssh://git@kgit.net:2222/kore/kola/kola.git
cd kola
cargo build --release -p kola-cli
target/release/kola --version

The binary is called kola. Older material calls it klc, a name that no longer exists. The examples below assume target/release is on your PATH.

The first program

Save this as hello.kl:

use std::log;

fn main() -> u8 !{log} {
    log::info("hello, kola");
    0
}

main returns a u8, the exit status: the small number a finished program hands back to whoever started it, where 0 means success (a shell shows it as $?). The !{log} after the return type is the effect row, the complete list of what the function may do: here, write to the process log. The program needs nothing from the outside world, so main takes no parameters. A program that reads the clock, opens a file or writes to standard output declares fn main(sys: Sys) and receives the root capability set. A capability is a value that grants access to one part of the world, such as the clock or a directory; a function that was not handed one cannot reach that part at all.

The log is for diagnostics. Whoever starts the program chooses its sink (--log stderr|stdout|file:PATH|off; stderr by default), and the program can only write to it. Output for another program to parse goes through the sys.stdout capability instead.

Check, run, and test

kola check hello.kl
kola run hello.kl

check runs the whole static discipline: types, regions, linearity, effects, capabilities and contracts. run interprets main and prints [info] hello, kola. Interpreting means executing the program directly, without first producing machine code. kola also has backends, the parts of the compiler that turn a checked program into native code; the interpreter is the reference implementation they are all compared against.

Tests live in the same file as the code. Save this as area.kl:

fn area(w: u32, h: u32) -> u64 !{} {
    widen[u64](w) * widen[u64](h)
}

test area_works {
    assert area(3, 4) == 12;
    assert area(0, 100) == 0;
}

kola test area.kl

kola test runs every test item on the interpreter and through the C backend (which translates the program to C and compiles that with your system's C compiler) and compares the answers file by file; if they disagree, it exits with status 3. --interp runs the interpreter alone and needs no C compiler, which makes it the fast loop while you iterate. --native runs only the C backend.

Build an executable

kola build hello.kl --link hello
./hello

With --link, kola first tries its own backend, which writes an executable for Linux, macOS or Windows on x86-64 or AArch64 without a C compiler or linker. (A linker is the tool that joins compiled pieces of code into one runnable file; normally it comes with the C toolchain.) If the own backend refuses the program, kola says why and builds through the C compiler instead. --native selects the C path directly.

Without --link, kola build emits C into a build/ directory beside the source and compiles it to an object file (a .o file: compiled code that is not yet a complete program), for linking into a C program (Embedding kola in a C program). --cross --target <triple> uses the own backend alone, with its full list of targets.

The cards and the embedded standard library

SPEC-CARD.md defines the language and STD-CARD.md the standard library. Both are compiled into the binary, so what you read matches the compiler you run:

kola help spec-card
kola help std-card
kola help std-index

std-index lists every public item of the standard library: the quickest way to find out whether a function exists. kola help <command> documents each command.

The standard library is embedded too. If you edit the repository's std/ directory, pass --std std so kola reads your working tree; otherwise your edits have no effect.

When an example fails

Every diagnostic cites the card section it enforces (error[card §6]) and usually proposes a repair. Read that section rather than guessing at a fix. If an example on these pages fails against your compiler, the page is stale: report its title, the command and the diagnostic.