Installation

There are two ways to get Kairo: download a prebuilt binary (fastest), or build from source. Most users want the prebuilt binary.

Kairo ships as two compilers:

• Stage 0 the current compiler, written in C++. It transpiles Kairo to C++ and does not require LLVM. This is what almost everyone wants.
• Stage 1 the self-hosted compiler, written in Kairo (work in progress). Building it requires a working Stage 0 compiler and the LLVM submodule.

Unless you are developing Kairo itself, install Stage 0 and stop there.

Prebuilt Binaries

Download the archive for your platform from the release page, extract it, and add the bin directory to your PATH.

System requirements

• Linux: glibc 2.35 or newer (Ubuntu 22.04+, Debian 12+, RHEL 9+, Fedora 37+)
• macOS: 13.3 (Ventura) or newer
• Windows: Windows 10 or newer no Visual C++ Redistributable required, the runtime is statically linked

The Linux binaries are self-contained no system libc++ or libunwind required.

xattr -dr com.apple.quarantine ./kairo

Building from Source

Requirements

Stage 0 requires:

• Clang 18 or newer libstdc++ is not supported, you must build with Clang and libc++
• libc++ and libc++abi
• xmake the build system
• git

Stage 1 additionally requires the LLVM submodule (see below). The VSCode extension additionally requires Node.js and npm.

1. Install dependencies

Every platform needs Clang 18+ with libc++. The sections below show how to get a satisfying toolchain.

Linux Arch / Manjaro

Arch’s clang is current (well past 18), so no version pinning is needed.

sudo pacman -S git clang libc++ libc++abi lld cmake ninja xmake

Linux Ubuntu / Debian

The distro Clang is often older than 18 or defaults to libstdc++, so install from LLVM’s apt repo (18 is the minimum; newer is fine):

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 18
sudo apt-get install -y libc++-18-dev libc++abi-18-dev git
# make clang-18 the default clang/clang++
sudo update-alternatives --install /usr/bin/clang   clang   /usr/bin/clang-18   100
sudo update-alternatives --install /usr/bin/clang++ clang++ /usr/bin/clang++-18 100

Linux Fedora / RHEL

Ensure clang --version reports 18+. Older RHEL ships an older toolchain you may need a newer LLVM module to meet the minimum.

sudo dnf install -y clang libcxx-devel libcxxabi-devel git cmake ninja-build

Then install xmake on any Linux distro that did not already provide it:

curl -fsSL https://xmake.io/shget.text | bash

macOS

Install the LLVM toolchain and xmake with Homebrew, then put Homebrew’s Clang on your PATH:

brew install llvm xmake
echo 'export PATH="'"$(brew --prefix llvm)"'/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows

Install xmake in PowerShell:

irm https://xmake.io/psget.text | iex

For the compiler toolchain, install Visual Studio with the “Desktop development with C++” workload, or LLVM for Windows from releases.llvm.org. xmake detects the toolchain automatically.

2. Clone the repository

git clone https://github.com/kairolang/kairo/
cd kairo
git checkout archive/beta-helix-0.0.1

Pull submodules. For Stage 0 this is a fast clone it does not pull LLVM:

git submodule update --init --recursive

3. Build Stage 0

xmake

No flags needed. The build produces a self-contained compiler in build/release/<platform>/bin/: kairo and kbld.

4. Add to PATH

Linux / macOS:

export PATH="$PATH:$(ls -d $(pwd)/build/release/*/bin)"

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

Windows (PowerShell):

$env:Path += ";$((Get-ChildItem -Directory .\build\release\*\bin).FullName)"

This sets PATH for the current session. To persist it across sessions:

$binPath = (Get-ChildItem -Directory .\build\release\*\bin).FullName
[Environment]::SetEnvironmentVariable("Path", "$env:Path;$binPath", "User")

For Command Prompt, add the path via System Properties -> Environment Variables.

5. Validate

Create a file called test.k:

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

Compile and run it:

kairo test.k

Stage 1 (optional)

Stage 1 is the self-hosted compiler, still in development. It requires a working Stage 0 build (above) plus the LLVM submodule.

git checkout canary
git submodule update --init --recursive   # pulls LLVM this time large download
kbld                                       # must be on PATH, or use ./build/release/<platform>/bin/kbld

You can run test files whose entry point is fn Test() -> i32 { ... }:

kbld test Compiler/Lexer/Lexer.k

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