Karkain 1.2.0 (Stable) — Karkain is a working compiler and language, not an empty roadmap. Everything labeled Implemented below is verified by automated gates through the real CLI. Everything else is honestly labeled
Planned/Not Yet Implemented.
Karkain is a statically typed systems programming language with a
self-hosted compiler, a byte-identical dual-engine pipeline, a real standard
library, native executables, cross-compilation, and a byte-identical
concurrency surface (WASM is a Go-engine production candidate). It compiles
.kark source to C23 and delegates to a
host C compiler (GCC/Clang/MSVC) for final machine code.
Honesty policy: the status vocabulary in
docs/source/status/index.rst governs every
claim in this project — a feature is Implemented only when an automated
gate test exercises it through the real pipeline. See the
capability summary.
Karkain builds from source with Go 1.21+ and any C compiler.
git clone https://github.com/ajit-ai/Karkain.git
cd Karkain
go build -o karkain ./cmd/karkain # Windows: go build -o karkain.exe ./cmd/karkain
./karkain --version # Karkain Compiler v1.2.0 (..., Stable Build)Write your first program:
// hello.kark
func main() {
println("Hello, Karkain!")
}
Run it:
karkain run hello.kark
karkain check hello.kark # syntax + semantics, exit 3 on error
karkain build hello.kark # native executableDocumentation:
- Getting Started — installation, first program, project layout ](docs/source/examples/index.rst) — 59 real, runnable programs
- Language Guide — the language as it actually works
- Standard Library —
std.string,std.collections,std.io,std.encoding,std.crypto,std.testing - CLI Reference — every command, flag and exit code
- Compiler Architecture — the Go front end and the self-hosted
kccengine - Targets & Cross-Compilation — host matrix, triples, WASM
- Status & Roadmap — what works, what is planned
- Contributing — how to help
- Security — private vulnerability reporting
Implemented (gated, byte-identical on both the Go front end and the
self-hosted kcc engine):
- Language core —
let/var/const,func,while,if/else,for-inand C-stylefor, structs (records), enums,matchon literals andOption, arrays, strings, maps (withstd.collectionshelpers) - C-free native targets (v1.2.0, Sovereignty I) —
karkain build --target native-x86_64-<windows|linux|macos>emits a linked executable with no C compiler and no Go toolchain onPATH. The images are produced by the self-hosted engine: its own value model, machine-code encoder and ELF / PE / Mach-O container writers. The qualified subset covers integer expressions, user functions, branches, loops, array indexing and the bounds diagnostic; everything outside it is refused by name, with no image. Windows PE images are executed and byte-checked; the Linux ELF is byte-identical to the Go oracle and executes on the Linux CI leg; the macOS Mach-O is structurally validated (this repository has no macOS runner). - Standard library — 6 importable modules with NIST/RFC-verified digest and codec behavior
- CLI —
check,build,run,test(+--filter),transpile,fmt,lint,debug,prof,target,pkg,workspace,clean,explain,bench,lsp,new - Self-hosting —
kccis the default engine forcheck/build/run/test, it owns the native back end and the machine-code encoders, and the stage-2 == stage-3 bootstrap identity was proven bitwise identical - Cross-compilation —
karkain build --target <triple>with honest "no cross-linker" diagnostics, never a silent host fallback - Runtime error model — checked div/mod/indexing report
runtime error: <kind> at <file>:<line>with stack traces - Developer tooling — formatter, linter, LSP server, VS Code extension, DWARF debug info, incremental compilation, profiling
WASM bounds (Go engine; the self-hosted kcc parity is the documented
boundary):
- WASM target (Phases 108/123) —
karkain build --target wasm32-wasiemits deterministic WASM binaries; run withwasmtime. WASI exit codes,stderrdiagnostics andgetArgs()are implemented. Classified production candidate.
Neuro/heterogeneous work:
- AI / ML — hand-rolled arithmetic demonstrations only (nearest neighbor, linear classifier, regression, gradient descent). No tensor language surface.
- Scientific computing / finance / security — Newton sqrt, numerical integration, statistics, matrix multiply, compound interest, loan amortization, net-present value, SHA-256/SHA-512 digests, hex/Base64, UTF-8 round-trips. All real.
| Capability | Status |
|---|---|
| Networking (TCP/UDP/HTTP) | Implemented (std.net, std.http, Phase 125A) |
| Databases | Implemented (std.db SQL-text engine, Phase 125A) |
| Web framework | Partial (std.http primitives; no routing/middleware/TLS) |
| Quantum language surface | Not Yet Implemented (infrastructure only) |
| GPU/NPU kernel language surface | Implemented (@target(gpu)/@target(npu), Phases 98/138; compile-only guarantee) |
| Advanced package registry | Not Yet Implemented (local resolution + lockfiles only) |
| Pre-built release binaries | Available - 13 v1.2.0 archives with a checksums.txt (see the Installation guide) |
Experimental means real and testable, but the surface may change:
- Concurrency runtime (Phase 107) —
spawn/join, channels, actors, byte-identical on both engines since Phase 137. - SIMD/vector types (Phase 106) —
[N]f32/[N]f64/[N]i32/[N]i64with@simd_*builtins. - Profiling & debug trace —
karkain profandkarkain debug, both Go-engine instrumentation.
examples/ holds 61 real .kark programs across 15 categories — 58
Runnable (incl. test-mode), 2 Stable, 1 Planned (README only).
karkain run examples/01-fundamentals/01_hello_world.kark
karkain test examples/15-developer-tools/02_assertions_test.kark
powershell -ExecutionPolicy Bypass -File scripts\verify-examples.ps1Every Runnable example is pinned to a golden output on both engines by
pkg/cli/phase114_examples_test.go. The authoritative inventory and status
per file lives in examples/EXAMPLES.md.
// Functions
func add(a: int, b: int) -> int {
return a + b
}
// Control flow
func classify(n: int) -> string {
if n < 10 {
return "small"
} else {
return "big"
}
}
// Records
struct Counter {
value: int
owner: string
}
// Options and match
func maybe(x: int) {
let o: Option<int> = Some(x)
match o {
Some(v) => println(v)
None => println("none")
}
}
func main() {
let c = Counter { value: 1, owner: "karkain" }
println(add(c.value, 41))
println(classify(42))
maybe(7)
}
std.encoding / std.crypto modules:
import std.crypto
import std.encoding
func main() {
println(hex_encode(bytes("karkain"))) // 6b61726b61696e
println(sha256("abc")) // ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
}
karkain run hello.kark # compile and run (default)
karkain build hello.kark # native executable
karkain transpile hello.kark # keep the generated C source
karkain check hello.kark # validate syntax + semantics
karkain test path/ # discover *_test.kark, run, --filter
karkain fmt hello.kark # canonicalize formatting (--check to verify)
karkain lint hello.kark # full front-end analysis incl. borrow checking
karkain debug hello.kark # opt-in function enter/leave trace (Go engine)
karkain prof hello.kark # per-function counts/timings/flame-graph data (Go engine)
karkain target # host triple + supported target matrix
karkain build hello.kark --target wasm32-wasi # WASM (needs wasmtime to run)
karkain lsp # Language Server Protocol over stdio
karkain pkg init myapp # new project skeleton
Use -h/--help on any command for its full options. Exit codes: 0 success,
1 program/failure, 2 usage, 3 compile/check error, 4 test failure, 6 missing
toolchain, 7 lint findings.
Prerequisites: Go 1.21+, a C compiler (GCC, Clang, or MSVC), Git.
# Clone
git clone https://github.com/ajit-ai/Karkain.git
cd Karkain
# Build (Linux/macOS/FreeBSD)
go build -o karkain ./cmd/karkain
# Build (Windows PowerShell)
go build -o karkain.exe ./cmd/karkain
# Test (unit suites)
go test ./pkg/lexer/... ./pkg/parser/... ./pkg/codegen/... ./pkg/pm/... -count=1
# Release-readiness gate
go test ./pkg/cli/ -run TestPhase115 -count=1
# Docs (Sphinx)
python -m pip install -r docs/requirements.txt
python -m sphinx -b html docs/source docs/build/html -W --keep-goingThe default engine is the self-hosted kcc compiler. The Go front end is
selected with KARKAIN_ENGINE=go or --engine go.
karkain build --target <triple> compiles for a requested
architecture/OS. Same-machine targets reuse the host C toolchain; foreign
targets use a triple-prefixed GNU cross-gcc (then clang --target). Without
a cross-linker the build fails deterministically with a diagnostic listing
exactly what was searched — never a wrong-architecture binary.
karkain build app.kark --target x86_64-windows # native PE32+ on Windows
karkain build app.kark --target x86_64-linux # needs a cross-linker here
karkain target # host triple + matrixkarkain run --target <foreign> is refused (cross-run needs an emulator or
remote target). wasm32-wasi uses the Karkain-owned WASM backend (production
candidate, wasmtime-gated).
Karkain/
├── cmd/karkain/ # CLI entry point
├── pkg/
│ ├── lexer/ parser/ sema/ codegen/ ir/ssa/
│ ├── cli/ # command handlers + phase gates
│ ├── pm/ # package manager (local resolution)
│ ├── target/ # cross-compilation target model
│ ├── wasm/ # wasm32-wasi emitter
│ ├── compiler/ # incremental compilation cache
│ ├── bootstrap/ # self-hosting bootstrap
│ ├── lsp/ diagnostics/ source/ testing/ runtime/ backend/ npu/
├── src/compiler/ # self-hosted compiler, written in .kark
├── stdlib/ # Karkain standard library sources (.kark)
├── conformance/ # 59 native test_* functions, both engines
├── examples/ # 52 examples across 15 categories
├── scripts/ # build / release / verify scripts
├── docs/ # Sphinx documentation + phase audit reports
├── .github/workflows/ # CI and docs publishing
├── go.mod
├── LICENSE
├── CONTRIBUTING.md
└── README.md
See ROADMAP.md for the full development plan (phases 50-149
delivered, plus the Sovereignty I track to 1.2.0). The project label is now
Karkain 1.2.0 (Stable), the Native Independence release (1.0.x continues
as the LTS line).
High-level status today: the compiler is self-hosted, byte-identical on two
engines, and the standard library (incl. networking, database and web
modules), toolchain and example corpus are real and regression-gated —
while the package registry and the JIT tier remain
Planned/Not Yet Implemented. The 1.0.0 release verdict and evidence are
documented in the Phase 119 QA report
(docs/audit/PHASE-119-LANGUAGE-QA-FINAL-REPORT.md); the 1.2.0 story is in
docs/audit/KARKAIN-V1.2.0-GA-QUALIFICATION.md.
Feedback and contributions are welcome. Start with CONTRIBUTING.md, then:
- Fork the repository.
- Create a feature branch off
develop. - Build and test:
go test ./pkg/lexer/... ./pkg/parser/... ./pkg/codegen/... ./pkg/pm/... -count=1 - Submit a pull request (PRs are reviewed on the
developbranch).
Report bugs and feature requests at
https://github.com/ajit-ai/Karkain/issues.
Use the bug report template; include
karkain --version output and a minimal source file. For security
vulnerabilities use the private path in SECURITY.md — do
not open a public issue.
Karkain is developed and maintained by Ajit Kumar. See AUTHORS for the full attribution list and contributor guidelines.
MIT — see LICENSE. In short: use it, modify it, ship it; the software is provided "as is" without warranty.