Installation

Karkain is distributed as pre-compiled binaries and built from source.

Note

Karkain is 1.2.0 (Stable) software. The stable core is regression-gated; experimental surfaces may change between releases.

Pre-compiled binaries

Available — pre-built binaries for v1.2.0 have been built and validated as a 13-archive set. The v1.2.0 GitHub Release publishes them to GitHub Releases with a checksums.txt (SHA-256) listing; Release status below records whether the release is live and how it was built. The v1.2.0 archives were built locally on a Windows host from the tagged commit (``v1.2.0``, peeled commit ``77d7069``) using Go 1.21.13 — the Go version the CI workflow pins — with ``CGO_ENABLED=0`` and the CI build flags. GitHub Actions could not execute the release matrix because the account was subject to a billing/payment restriction, so this is a locally built and published release, NOT a CI-green release. Each archive contains the karkain binary, the standard library, README.md, LICENSE and a VERSION file. The repository install/verify scripts also build from source; see Building from source.

Release status

Note

Available - the v1.2.0 archives are published to GitHub Releases, together with a checksums.txt (SHA-256) listing. They are locally built and published, NOT a CI-green release: they were built on a Windows host from the tagged commit with Go 1.21.13 (the CI workflow’s Go version), and the tag-triggered CI pipeline did not complete because the account was subject to a billing/payment restriction. Verify every archive against that file before running it; the exact commands are in Building from source below. The build-from-source path remains the way to get the toolchain for an unlisted platform.

Note

The binaries ship the self-contained Go engine. The self-hosted kcc engine (the default engine when present) is compiled from the repository’s src/compiler sources, so to use it: run from a clone of the repository, or point the KARKAIN_KCC environment variable at an src/compiler directory. To use the self-contained Go engine instead, pass --engine go to karkain (or set KARKAIN_ENGINE=go).

Note

Go is reference-only for the C-free native targets, not globally. The three native-x86_64-* targets build with no C compiler at all, and all three are emitted by the self-hosted engine (kcc): native-x86_64-windows since Phase 151D, native-x86_64-linux since Phase A1, and native-x86_64-macos since Phase B. The Go toolchain is still a prerequisite for building the compiler itself, and the Go backend remains the reference implementation the native differential compares against. See Host Targets for the ownership table and for what is proven by execution and what is proven structurally.

Archive naming convention:

Platform

Architecture

Archive (v1.2.0)

Status

Windows

amd64

karkain-v1.2.0-windows-amd64.zip

Available

Windows

arm64

karkain-v1.2.0-windows-arm64.zip

Available

Linux

amd64

karkain-v1.2.0-linux-amd64.tar.gz

Available

Linux

arm64

karkain-v1.2.0-linux-arm64.tar.gz

Available

Linux

arm (ARMv7)

karkain-v1.2.0-linux-arm.tar.gz

Available

Linux

386

karkain-v1.2.0-linux-386.tar.gz

Available

Linux

ppc64le

karkain-v1.2.0-linux-ppc64le.tar.gz

Available

Linux

s390x

karkain-v1.2.0-linux-s390x.tar.gz

Available

macOS

amd64

karkain-v1.2.0-darwin-amd64.tar.gz

Available

macOS

arm64

karkain-v1.2.0-darwin-arm64.tar.gz

Available

FreeBSD

amd64

karkain-v1.2.0-freebsd-amd64.tar.gz

Available

NetBSD

amd64

karkain-v1.2.0-netbsd-amd64.tar.gz

Available

OpenBSD

amd64

karkain-v1.2.0-openbsd-amd64.tar.gz

Available

Docker

(multi-arch)

ghcr.io/ajit-ai/karkain:latest

Planned

Windows

# Once the v1.0.0 GitHub Release is published, download the archive and:
Expand-Archive -Path .\karkain-v1.2.0-windows-amd64.zip -DestinationPath $env:LOCALAPPDATA\Karkain

# Add to PATH (PowerShell)
$env:PATH += ";$env:LOCALAPPDATA\Karkain\karkain-v1.2.0-windows-amd64"

# Verify
karkain --version

Linux

tar xzf karkain-v1.2.0-linux-amd64.tar.gz
sudo mv karkain-v1.2.0-linux-amd64/karkain /usr/local/bin/
karkain --version

macOS

tar xzf karkain-v1.2.0-darwin-amd64.tar.gz
sudo mv karkain-v1.2.0-darwin-amd64/karkain /usr/local/bin/
karkain --version

Verifying the download

Every archive is listed in the release’s checksums.txt file (SHA-256). Always verify a downloaded archive against it before running:

# Linux / macOS: compare the published checksum with the local file
sha256sum -c checksums.txt --ignore-missing   # (checks every listed file)

# Or check one archive directly:
grep "karkain-v1.2.0-linux-amd64.tar.gz" checksums.txt
echo "<published-sha256>  karkain-v1.2.0-linux-amd64.tar.gz" | sha256sum -c -

Windows (PowerShell):

Get-FileHash .\karkain-v1.2.0-windows-amd64.zip -Algorithm SHA256

# Compare the output hash with the published value in checksums.txt; a
# matching SHA-256 means the archive is intact and authentic.

Docker

Note

Planned — the container image is not published yet; use the pre-compiled binary or build from source.

docker run -it ghcr.io/ajit-ai/karkain:latest karkain --version

Building from source

Requirements:

  • Go 1.21+

  • GCC or Clang (for the C transpilation backend)

  • Git

git clone https://github.com/ajit-ai/Karkain.git
cd Karkain
go build ./cmd/karkain
./karkain --version

On Windows with PowerShell:

go build ./cmd/karkain
.\karkain.exe --version

Verified install script

The repository ships deterministic install scripts that build, install and smoke-test the toolchain with explicit exit codes:

powershell -ExecutionPolicy Bypass -File scripts\install.ps1
powershell -ExecutionPolicy Bypass -File scripts\verify-install.ps1

# Linux / macOS (bash)
./scripts/install.sh

The scripts verify prerequisites (Go 1.21+ and a C compiler), build karkain into the prefix ($LOCALAPPDATA\Karkain on Windows, $HOME/.local/karkain elsewhere), check karkain --help and compile + run hello.kark. Exit codes are deterministic: 0 success, 1 missing prerequisite, 2 build failure, 3 installation smoke-test failure.

Minimum practical development environment

The compiler itself is lightweight, but two parts of the ecosystem have real resource needs:

  • Building the full test suite — running every pkg/cli gate concurrently can exhaust machines with very limited RAM. On memory-constrained hosts (about 4 GB or less of usable RAM), run the CLI gates sequentially or batched by phase (e.g. go test ./pkg/cli/ -run 'TestPhase11[45678]'), not go test ./pkg/cli/ -count=1 all at once. This is a documented environmental behavior, not a toolchain defect.

  • Full ``kcc`` *build* mode — transpiling the compiler’s own sources with kcc build can stall on very limited hosts; the low-memory kcc check path works everywhere. See Beta 1.

The recommended practical setup is a machine with at least 4 GB of RAM and a recent Go toolchain; single-program check/build/run work fine well below that.

Runtime requirements

The Karkain toolchain requires:

  • A C compiler (GCC, Clang, or MSVC) on the host platform

  • Git (for the package manager’s dependency fetching)

  • Go (for building Karkain from source or running the Go engine)

Optional:

  • wasmtime — required only for wasm32-wasi targets

  • GMP — optional big-integer backend (not required for standard usage)