Installation

Install the Khora toolchain once, then use khora to manage compiler versions for all of your projects. There is no separate version manager to install.

Install Khora

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/codyspate/khoralang/main/install.sh | sh

The script needs curl or wget, tar, and CA certificates. A desktop or a CI runner has them; a slim container image often does not — on debian:*-slim, apt-get install -y curl ca-certificates first.

Running it as root, in a Dockerfile or a CI step, is supported.

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/codyspate/khoralang/main/install.ps1 | iex

The installer downloads the build for your platform, verifies it against the published checksum, and installs it under ~/.khora — or under $KHORA_HOME when that variable is set, which is also where every later khora command looks for toolchains. The installer prints the directory it used. It does not compile Khora from source and does not require administrator access.

Verify the installation:

khora --version

Then continue with Getting Started or Your first Khora project.

Verify what you downloaded

Every archive is published with a .sha256 beside it, and the installer checks it. If you fetched an archive by hand, the release page lists both, at

https://github.com/codyspate/khoralang/releases/download/v<version>/khora-<version>-<target>.tar.gz
https://github.com/codyspate/khoralang/releases/download/v<version>/khora-<version>-<target>.tar.gz.sha256

(.zip on Windows), and you check it the same way:

sha256sum -c khora-0.3.0-x86_64-unknown-linux-gnu.tar.gz.sha256

A checksum says the bytes are the ones that were published. It does not say who published them, and anybody who can replace the archive can replace the checksum next to it. For that, every archive also carries build provenance: a signed statement, made by GitHub during the release run, of which workflow in which repository at which commit produced that exact file. Checking it needs the GitHub CLI signed in to any account (gh auth login):

gh attestation verify khora-0.3.0-x86_64-unknown-linux-gnu.tar.gz   --repo codyspate/khoralang

There is no maintainer key to trust and none to leak. The signing identity is the release workflow’s own, which is also why nothing is published from anybody’s workstation.

What is in the toolchain

Each release includes a bill of materials as khora-<version>.cdx.json, in CycloneDX 1.5, listing every Rust crate compiled into the toolchain with its version and licence, the pinned LLVM, and the Rust toolchain that built it. Dependency scanners read it directly.

That document is about the compiler. For the other question — what does the program I am building pull in — khora sbom renders the same format from your package’s own resolution:

khora sbom --out my-app.cdx.json

It is rendered from the resolution rather than from a lockfile read off disk, so it describes what a build here would use. Pass --locked to refuse a stale lockfile instead of absorbing the difference.

Linux system requirements

The published Linux build is dynamically linked against glibc, and a glibc program cannot run against a library older than the one it was compiled against. The release is built on Ubuntu 24.04, so the published x86_64-unknown-linux-gnu build requires glibc 2.39 or newer.

That is a real constraint and not a rounding error. Distributions in wide use today are on both sides of it:

distribution	glibc	the published build
Ubuntu 24.04 LTS	2.39	runs
Debian 13 (trixie)	2.41	runs
Debian 12 (bookworm)	2.36	does not run
Ubuntu 22.04 LTS	2.35	does not run
RHEL 9 and rebuilds	2.34	does not run
Alpine, and anything on musl	not glibc	does not run

install.sh checks this before it downloads anything, and refuses with the two numbers rather than installing a toolchain that cannot start. If you are on a distribution below the line, the options are a newer distribution — including a container built on one — or building from source, which links the compiler against the glibc you have.

Check yours with:

ldd --version | head -1

This is a property of the toolchain, not of the programs you compile with it: a program built by Khora is linked against the machine that built it, so building on Ubuntu 24.04 and deploying to Debian 12 has the same problem for the same reason. Containers says to use the same base image in both stages, which is that advice.

System linker requirement

Khora compiles to native object code, so producing an executable requires the platform’s linker, C runtime, and system libraries. You do not need to install LLVM separately; LLVM is linked into the Khora compiler rather than invoked as an external program.

Platform	Linker/toolchain
macOS	xcode-select --install
Debian / Ubuntu	apt install clang or apt install build-essential
Fedora / RHEL	dnf install clang or dnf install gcc
Windows	LLVM, or the Visual Studio Build Tools with the C++ Clang tools for Windows component

On Linux and macOS any of clang, cc or gcc will do as the driver. Windows needs clang specifically: the Desktop development with C++ workload does not install it by itself — its C++ Clang tools for Windows component is separate — and MSVC’s own cl.exe is not a substitute, because the driver is what locates the C runtime and system libraries. Installing LLVM is the shorter route.

The installer checks for a usable linker and tells you if one is missing.

Update and manage toolchains

Use khora itself to install and switch compiler versions:

khora update                      # install the newest release and use it
khora toolchain install 0.3.0     # install a particular release
khora toolchain default 0.1.0     # select an installed release as the default
khora toolchain list              # list installed toolchains
khora toolchain which             # show the version selected here and why

Updating does not remove the version it replaces, so rolling back is a toolchain selection rather than a reinstall.

Pin a project to a compiler version

Every project says which compiler builds it, in khora.toml:

[toolchain]
version = "0.3.0"

The field is required. A project without it stops with a message carrying the two lines to add — the version, the quoting and the table name are not things anybody should have to guess.

A project pin takes precedence over your machine default. If the pinned version is not installed, Khora stops rather than silently building the project with a different compiler.

latest and latest.rc are accepted in place of a version, and mean the newest toolchain installed on this machine, release candidates excluded or included. They resolve whenever they are read, so they are not reproducible — write a version for a project you want built the same way twice.

That makes the compiler version part of the reproducible project configuration:

khora toolchain which

shows which version the current directory selects.

Uninstall

The default installation lives under ~/.khora. If you no longer want Khora installed, remove that directory and remove any Khora path entry you added manually.

Build the compiler from source

Building from source is for contributing to Khora itself, testing compiler changes, or working on a platform without a published toolchain artifact. Application developers normally use the installer above.

Requirements are Git, a current Rust toolchain, and LLVM 22.1.8 for native code generation.

git clone https://github.com/codyspate/khoralang.git
cd khoralang
sh scripts/setup-llvm.sh
cargo build -p khora-cli --features llvm
cargo build -p khora-rt

scripts/setup-llvm.sh installs or locates the pinned LLVM version and writes the machine-specific Cargo configuration needed by the backend.

You can register a compiler you built locally as a Khora toolchain:

khora toolchain link 0.3.0 target/debug/khora

Release candidates

If you intentionally want to test a release candidate, opt into prerelease versions explicitly. These pages — the next documentation — describe the newest candidate, and the release page on GitHub names which one that is.

On macOS or Linux, the newest release including candidates, or one by name:

curl -fsSL https://raw.githubusercontent.com/codyspate/khoralang/main/install.sh | sh -s -- --pre
curl -fsSL https://raw.githubusercontent.com/codyspate/khoralang/main/install.sh | sh -s -- --version 0.3.0-rc.1

--version takes the version without the leading v, and works for any published release, candidate or not.

On Windows PowerShell, installrc.ps1 is install.ps1 with prereleases allowed — PowerShell cannot pass an argument to a script piped into iex, so the option is a second file rather than a flag:

irm https://raw.githubusercontent.com/codyspate/khoralang/main/installrc.ps1 | iex

After a Khora toolchain is installed, the normal toolchain commands can also include prereleases:

khora toolchain install --pre
khora update --pre

--pre means prereleases are eligible; it does not prevent the tool from selecting a newer stable release. Release candidates have their own immutable version numbers such as 0.2.0-rc.1 and are not promoted in place.

A project built with a candidate pins it by its full name — khora new writes the pin for whichever compiler ran it:

[toolchain]
version = "0.3.0-rc.1"

When you are ready to write code, continue with Your first Khora project.