Installation

Installation

Kairo 0.2.3 ships as a prebuilt package for 14 host platforms: Linux (static musl, runs on any distribution), Windows, macOS and the BSDs. Pick your archive in the table below, or let the install script choose it. A host without an archive can build from source.

The compiler, kairo, is written in Kairo and compiles itself. The package holds everything it needs: kairo, kcc, kld, kfmt, ksys, kals (the language server), the builtin, std and rt libraries, compiler-rt, the host's own sysroots and the sources ksys builds every other target's sysroot from. Clang and LLD run inside kairo, kcc and kld, so no separate clang or lld binaries ship. You do not need a system C or C++ toolchain.


Prebuilt Package

Quick install

Linux, macOS, FreeBSD and NetBSD (any shell, fish included):

curl -fsSL https://www.kairolang.org/install.sh | sh

Windows (PowerShell 5.1 or 7):

irm https://www.kairolang.org/install.ps1 | iex

Both are the same script. It detects your OS and CPU, downloads the matching archive and SHA256SUMS, verifies the checksum before unpacking, and never needs root or administrator rights. On Linux, macOS and the BSDs it unpacks to ~/.local/share/kairo/<version> and links the tools into ~/.local/bin. On Windows it unpacks to %LOCALAPPDATA%\Kairo\<version> and adds that bin directory to your user Path. It honours KAIRO_VERSION, KAIRO_PREFIX, KAIRO_BASE_URL and KAIRO_TRIPLE; set KAIRO_TRIPLE to pick a different archive from the table (for example armv7-windows-gnu).

Manual download

Download the archive and SHA256SUMS from the release page, verify it, extract it, and add bin to your PATH.

PlatformArchitectureFile
Linux (static, musl)x86_64kairo-0.2.3-x86_64-linux-musl.tar.xz
Linux (static, musl)aarch64kairo-0.2.3-aarch64-linux-musl.tar.xz
Linux (static, musl)armv7kairo-0.2.3-armv7-linux-musl.tar.xz
Linux (static, musl)i686kairo-0.2.3-i686-linux-musl.tar.xz
Linux (static, musl)riscv64kairo-0.2.3-riscv64-linux-musl.tar.xz
Windows (MinGW)x86_64kairo-0.2.3-x86_64-windows-gnu.zip
Windows (MinGW)aarch64kairo-0.2.3-aarch64-windows-gnu.zip
Windows (MinGW)armv7kairo-0.2.3-armv7-windows-gnu.zip
Windows (MinGW)i686kairo-0.2.3-i686-windows-gnu.zip
macOS 11+arm64kairo-0.2.3-arm64-apple-macosx11.0.zip
macOS 10.15+x86_64kairo-0.2.3-x86_64-apple-macosx10.15.zip
FreeBSDx86_64kairo-0.2.3-x86_64-unknown-freebsd.tar.xz
FreeBSDaarch64kairo-0.2.3-aarch64-unknown-freebsd.tar.xz
NetBSDx86_64kairo-0.2.3-x86_64-unknown-netbsd.tar.xz
sha256sum -c --ignore-missing SHA256SUMS
tar -xJf kairo-0.2.3-x86_64-linux-musl.tar.xz

The archive contains:

  • bin/: kairo, kcc, kld, kfmt, ksys, kals, llvm-symbolizer, llvm-ar, llvm-ranlib, llvm-lib
  • lib/: the clang resource directory, builtin, std and rt
  • sysroot/: the sysroots of the archive's own host (below); Linux archives hold the musl and glibc 2.31 roots of their architecture, Windows archives their -windows-gnu root, BSD and macOS archives none
  • share/kairo/sysroot/: the input tree ksys builds every other target's sysroot from (libc sources and headers, glibc symbol lists, mingw-w64 and wasi-libc sources, BSD base trees, licenses)
  • scripts/: msvc-sysroot.sh / msvc-sysroot.ps1 (they fetch the CRT and Windows SDK with xwin if you accept Microsoft's license) and darwin-sysroot.sh, which build the macOS and MSVC sysroots from your own SDK (below)
  • share/kairo/runtimes/: the LLVM runtimes source (libc++, compiler-rt builtins) that ksys and those scripts compile
  • LICENSE, NOTICE, LICENSES/, THIRD-PARTY-NOTICES

The compiler is built on an LLVM 22 toolchain from Kairo's patched fork, linked in-process.

Note

The test suite runs on x86_64 Linux only. Cross-compiled output for other targets has not been through the suite on those platforms.

Sysroots

A sysroot is the C library, headers and runtime libraries of a target. The archive ships the sysroots of its own host and builds every other one on demand, so it is also the cross-compiler for the supported targets with no extra download:

  • Linux musl: x86_64, x32, i686, aarch64, aarch64_be, armv6, armv7, thumbv7, riscv64, riscv32, powerpc, powerpc64, powerpc64le, s390x, mips, mipsel, mips64, mips64el, loongarch64; Linux glibc (2.17 to 2.42, 16 architectures): x86_64, i686, aarch64, aarch64_be, armv7, riscv32, riscv64, powerpc, powerpc64(le), s390x, mips, mipsel, mips64, mips64el, loongarch64
  • Windows (MinGW): x86_64, aarch64, i686, armv7 (*-windows-gnu)
  • FreeBSD: x86_64, aarch64; NetBSD: x86_64
  • WebAssembly: wasm32-wasi

Pass --target=<triple> to pick one. The first time you name a target whose sysroot is not in the archive, kairo and kcc build it with ksys from share/kairo/sysroot and cache it (in ~/.cache/kairo/sysroot, or $KAIRO_SYSROOT_CACHE); it takes 5 to 30 seconds and needs no network. Later builds find it in the cache. --no-sysroot-build turns the build into an error, --sysroot=<dir> names a sysroot you have, and --freestanding compiles without system headers and libraries. A target whose sysroot cannot be built, and for which there is no input tree, warns (P008W) and names the flag to pass.

The target name can carry a glibc version: x86_64-linux-gnu-glibc2.28 or x86_64-linux-gnu.2.28, any version from 2.17 to 2.42. Without one, Linux programs build against glibc 2.31, so they run on any distribution with glibc 2.31 or newer.

Apple's SDK and Microsoft's MSVC / Windows SDK are never shipped or generated, on any host. To target macOS or MSVC-ABI Windows, build that sysroot once with the scripts in scripts/ (next section): they read the SDK you have installed (or, for MSVC, fetch it with xwin after you accept Microsoft's license) and put the result under sysroot/, where Kairo finds it with no flags. Without one, --target for those triples stops with an error naming the script. See ksys and kairo, kcc & Cross-compilation.

macOS and MSVC targets

Apple's and Microsoft's licenses forbid redistributing their SDKs, so the package cannot include *-apple-macosx or *-windows-msvc sysroots, and ksys never builds them from the shipped tree. Instead it ships scripts in scripts/ that build them from your own copy. They compile libc++ and compiler-rt from the LLVM source in share/kairo/runtimes using the package's own kcc and kld, and write the root to sysroot/<target>, where kairo --target finds it with no flags. You need cmake, ninja and python3.

For MSVC on Linux, macOS or WSL, msvc-sysroot gets the CRT and Windows SDK for you with xwin:

<install>/scripts/msvc-sysroot.sh x86_64

It prints Microsoft's license and asks you to accept it; --accept-license or KAIRO_ACCEPT_MSVC_LICENSE=1 accepts it up front (a non-interactive run with neither stops). It uses xwin from $XWIN_BIN, else PATH, else downloads a pinned release (checked against its sha256) into share/kairo/tools/, and keeps the download in share/kairo/msvc-cache/ for later runs. To use a splat you made yourself:

xwin --accept-license --arch x86_64,aarch64,x86 splat --output ~/xwin
XWIN=~/xwin <install>/scripts/msvc-sysroot.sh x86_64

On Windows, the same script uses the installed Visual Studio (the "Desktop development with C++" workload) and Windows SDK:

powershell -ExecutionPolicy Bypass -File <install>\scripts\msvc-sysroot.ps1 x86_64

For macOS, on a Mac with the Command Line Tools installed (xcode-select --install):

<install>/scripts/darwin-sysroot.sh arm64

Each script accepts several architectures at once (x86_64 aarch64 i686, or arm64 x86_64 arm64e). Keep the generated roots on your machine: they contain Apple's or Microsoft's files.

You often do not need to run them. On a Mac, the first kairo or kcc build for macOS (the native default, or --target arm64-apple-macosx / x86_64-apple-macosx) assembles the root itself from the SDK it finds (SDKROOT, the selected Xcode or the Command Line Tools) and the prebuilt libc++ in share/kairo/sdk-overlays/, in a few seconds, into the ksys cache. On Windows, the first --target x86_64-windows-msvc build does the same from an xwin splat (XWIN, or the one msvc-sysroot cached) or, with Visual Studio's C++ tools installed, by running msvc-sysroot.ps1 for you. With neither, it stops with an error giving the exact command: the CRT and Windows SDK download asks for Microsoft's license, so Kairo never starts it on its own. The scripts remain the way to build arm64e (no prebuilt overlay) or to rebuild libc++ from source.

A macOS target without a version (x86_64-apple-macosx) compiles for the oldest macOS the roots support, 11.0 on arm64 and 10.15 on x86_64; name one (arm64-apple-macosx13.0) to raise it.

System requirements

  • Linux x86_64: any distribution. The compiler is statically linked against musl and needs no system libc, libc++ or libunwind.
  • Windows: the native *-windows-gnu archives need no extra runtime; they are MinGW builds.

Add to PATH

If you used the install script, add ~/.local/bin to your PATH if it is not already there. For a manual extract:

export PATH="$PATH:/path/to/kairo-0.2.3-x86_64-linux-musl/bin"

Add that line to your ~/.bashrc or ~/.zshrc to make it permanent.

Validate

Create a file called test.k:

import std::io

fn main() -> i32 {
    var x = 5
    var y = 10
    io::println(f"Hello, world! Sum of {x} and {y} is {x + y}")
    return 0
}

Compile and run it:

kairo test.k -o test
./test
Hello, world! Sum of 5 and 10 is 15

Without -o, the executable is written to a.out.

The executable targets the machine you compile on. On Linux that is the host's glibc triple (x86_64-linux-gnu), which links dynamically against the system libc. For a static executable, pass --target=x86_64-linux-musl. To build for another platform, pass its triple with --target.


Building from Source

Build from source if you need unreleased changes or are developing Kairo itself. The compiler is written in Kairo, so building it needs a seed: a prebuilt Kairo release (0.2.0 or newer) from above. Building without a seed is not possible.

Requirements

  • A prebuilt Kairo release (0.2.0+) as the seed, with its bin/ on your PATH (or named with --kairo)
  • git and Python 3
  • CMake and Ninja, used once to build the patched LLVM
  • About 30 GB of free disk and plenty of RAM for the first build; the patched LLVM is built once and reused

You do not need a system Clang or xmake. The earlier C++ bootstrap compiler, Stage 0, is retired.

Build

git clone https://github.com/kairolang/kairo/
cd kairo
git submodule update --init --recursive   # pulls the patched LLVM (large download)
python3 build.py --release --kairo /path/to/kairo-0.2.3-x86_64-linux-musl/bin/kairo kairo kcc kld kfmt ksys kals

The first build also builds the patched LLVM (once; later builds reuse it). --kairo names the bootstrap compiler; it can be left out when that kairo is on your PATH, and later builds use the last one they produced.

build.py builds the compiler with the bootstrap compiler, rebuilds it with the result (so the final compiler is built by itself), and stages a self-contained package in build/<triple>/release/, where <triple> is your host's static musl triple (x86_64-linux-musl on x86-64 Linux): bin/ holds kairo and kcc beside kld, kfmt, ksys, kals, llvm-symbolizer and the llvm-ar family (there are no clang or clang++ binaries: kairo and kcc run clang in-process and kld runs lld in-process), and lib/ holds the clang resource directory, the builtin, std and rt libraries and every shared library the binaries need. The compiler finds all of it from its own location, so it runs with no flags:

build/x86_64-linux-musl/release/bin/kairo main.k -o main

--debug builds an unoptimized compiler that is quicker to rebuild. --resource-dir, --builtins-dir, --std-dir and --sysroot override what the compiler finds. If one of them cannot be found the compiler warns, naming the path it searched and the flag to pass. Not having a sysroot is a warning too, unless you pass --freestanding.

To run the compiler's test suite: build/llvm/bin/llvm-lit Tests -s (it tests the most recently built compiler; set KAIRO_BIN to pick one).

Scripts/package_release.py turns a built tree into a release archive.


VSCode Extension

VSCode is currently the only editor with LSP support and .k syntax highlighting. The language server ships as part of the compiler, so there is nothing extra to run: the extension only needs to locate kairo.

Install

Pick whichever is easiest:

  • Marketplace: install from the Kairo extension page.
  • Prebuilt VSIX: download the latest .vsix from kairo-lsp (e.g. kairo-0.5.5.vsix), then in VSCode: Extensions -> ... -> Install from VSIX...
  • Build from source:
git clone https://github.com/kairolang/kairo-lsp/
cd kairo-lsp
npm install
npm run build --omit=dev
npx @vscode/vsce package

This produces a .vsix you install the same way.

Configure

If kairo is on your PATH, the extension finds it automatically, no configuration needed. Otherwise set kairo.path in your VSCode settings.json to the compiler's location. If it cannot find the compiler, you get a single "path not set" warning.

Debugging

  • Run Kairo File - runs and attaches the debugger
  • Run Kairo File with Args - prompts for comma-separated args (e.g. arg1,arg2,arg3)

Both work with fn main() or fn Test() entry points.

Warning

With fn Test(), VSCode redirects to a temporary file during debugging. Breakpoints work, but edits are not saved back to your original file. Re-running the debugger resets everything. Use fn main() for active development.


Troubleshooting

warning [P008W]: no sysroot found for target .... The target has no sysroot in the archive and there is no share/kairo/sysroot to build one from (or the sysroot/ directory is not next to bin/). Pass --sysroot=<dir>; see Sysroots.

error [P009E] with --target. ksys refused to build the sysroot: the target is not one it knows (ksys probe <target> says why), the input tree does not match its hashes, or a tool is missing. Nothing was built. kairo --explain P009E lists the causes; a build that ran and failed is P010E and names a log. See ksys.

error [P008E]: no sysroot found for target ... (a *-apple-macosx or *-windows-msvc target). These sysroots are never bundled; build one with the scripts in scripts/, see macOS and MSVC targets.

The install script says the archive "is not listed in SHA256SUMS". Your OS/CPU has no prebuilt archive (the error lists the ones that exist). Build from source, see Building from Source.