Быстрый старт

Здесь небольшая программа на kola проходит весь путь от исходника до проверенного и протестированного исполняемого файла.

Сборка компилятора

Компилятор написан на Rust, и для сборки нужен только инструментарий Rust. Собирать следует пакет kola-cli: крейт kola сам по себе — библиотека.

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

Исполняемый файл называется kola. В старых материалах встречается имя klc; его больше нет. Ниже предполагается, что каталог target/release добавлен в PATH.

Первая программа

Сохраните это в файл hello.kl:

use std::log;

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

main возвращает u8 — код завершения. Это небольшое число, которое закончившая работу программа отдаёт тому, кто её запустил; 0 означает успех (в оболочке его видно как $?). !{log} после типа результата — ряд эффектов, полный список того, что функции разрешено делать. Здесь в нём одно действие: запись в журнал процесса. От внешнего мира программе ничего не нужно, поэтому параметров у main нет. Программа, которая читает часы, открывает файл или пишет в стандартный вывод, объявляет fn main(sys: Sys) и получает корневой набор капабилити. Капабилити — это значение, дающее доступ к одной части мира, например к часам или к каталогу. Функция, которой её не передали, до этой части мира дотянуться не может вовсе.

Журнал предназначен для диагностики. Его приёмник выбирает тот, кто запускает программу (--log stderr|stdout|file:PATH|off, по умолчанию stderr), а сама программа может в него только писать. Вывод, который будет разбирать другая программа, идёт через капабилити sys.stdout.

Проверка, запуск и тесты

kola check hello.kl
kola run hello.kl

check выполняет все статические проверки: типы, регионы, линейность, эффекты, капабилити и контракты. run интерпретирует main и печатает [info] hello, kola. Интерпретировать — значит исполнять программу напрямую, не порождая сначала машинный код. Кроме интерпретатора, у kola есть бэкенды — части компилятора, которые превращают проверенную программу в машинный код. Интерпретатор служит эталонной реализацией, и с ним сверяются все бэкенды.

Тесты живут в том же файле, что и код. Сохраните это в 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 прогоняет каждый test и на интерпретаторе, и через C-бэкенд (он переводит программу на C и компилирует результат системным компилятором C), а затем сравнивает ответы файл за файлом. Если они расходятся, команда завершается с кодом 3. Флаг --interp запускает только интерпретатор и обходится без компилятора C, поэтому во время работы над кодом это самый быстрый цикл. --native запускает только C-бэкенд.

Сборка исполняемого файла

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

С флагом --link kola сначала пробует собственный бэкенд. Он пишет исполняемый файл для Linux, macOS или Windows на x86-64 или AArch64 без компилятора C и без компоновщика. (Компоновщик, или линкер, — инструмент, который собирает скомпилированные части кода в один запускаемый файл; обычно он входит в инструментарий C.) Если собственный бэкенд программу не принимает, kola объясняет почему и собирает её через компилятор C. --native сразу выбирает путь через C.

Без --link команда kola build генерирует C в каталог build/ рядом с исходником и компилирует его в объектный файл (файл .o — скомпилированный код, который ещё не является законченной программой). Такой файл подключают к программе на C (Встраивание kola в C-программу). --cross --target <triple> использует только собственный бэкенд, со всем списком его целевых платформ.

Карты и встроенная стандартная библиотека

SPEC-CARD.md определяет язык, STD-CARD.md — стандартную библиотеку. Обе карты вкомпилированы в исполняемый файл, так что прочитанное всегда соответствует тому компилятору, который вы запускаете:

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

std-index перечисляет все публичные элементы стандартной библиотеки — это самый быстрый способ узнать, существует ли функция. kola help <command> описывает каждую команду.

Стандартная библиотека тоже встроена в исполняемый файл. Если вы правите каталог std/ в репозитории, передайте --std std, чтобы kola читала рабочее дерево; иначе правки ни на что не повлияют.

Если пример не работает

Каждое сообщение компилятора ссылается на раздел карты, который оно проверяет (error[card §6]), и обычно предлагает исправление. Прочитайте этот раздел, вместо того чтобы угадывать. Если пример с этих страниц не проходит на вашем компиляторе, значит, страница устарела: сообщите её название, команду и текст диагностики.