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 |
|
Available |
Windows |
arm64 |
|
Available |
Linux |
amd64 |
|
Available |
Linux |
arm64 |
|
Available |
Linux |
arm (ARMv7) |
|
Available |
Linux |
386 |
|
Available |
Linux |
ppc64le |
|
Available |
Linux |
s390x |
|
Available |
macOS |
amd64 |
|
Available |
macOS |
arm64 |
|
Available |
FreeBSD |
amd64 |
|
Available |
NetBSD |
amd64 |
|
Available |
OpenBSD |
amd64 |
|
Available |
Docker |
(multi-arch) |
|
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/cligate 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]'), notgo test ./pkg/cli/ -count=1all at once. This is a documented environmental behavior, not a toolchain defect.Full ``kcc`` *build* mode — transpiling the compiler’s own sources with
kcc buildcan stall on very limited hosts; the low-memorykcc checkpath 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)