Kinglet (self-host)

Self-hosted Kinglet compiler: the .kl sources in this repo compile to bytecode (.kbc) that runs on the C++ VM from the bootstrap compiler. Round-trip against the bootstrap compiler is verified.

Kinglet is a statically typed, value-semantics language (see ADR 0002). This tree is the compiler implementation — lexer, parser, checker, and VM bytecode backend — not the language spec alone.

Prerequisites

• Bootstrap VM — a built kinglet binary (default: ../kinglet/out/Default/kinglet). Override with KINGLET=/path/to/kinglet.
• No other runtime dependencies; sources are plain .kl files.

Quick start

# Bootstrap compiler (C++ reference implementation)
export KINGLET_BOOTSTRAP=../kinglet/out/Default/kinglet   # adjust if needed

# Build toolchain (Ref → native .kinglet/out/compiler by default; stamp-cached)
./kinglet build

# Native compiler driver (no compiler.kbc on hot path)
.kinglet/out/compiler --check path/to/file.kl

# Shadow / VM path (prove, parser goldens): build bytecode explicitly
./kinglet build --backend vm
# The bootstrap Ref compiler doubles as the VM host (`--run`):
$KINGLET_BOOTSTRAP --run .kinglet/out/compiler.kbc --ast path/to/file.kl

# One-off native program (LLVM backend)
$KINGLET_BOOTSTRAP --native /tmp/out path/to/file.kl && /tmp/out

# Run the full test suite (rebuilds only on stamp miss)
bash tests/run_all.sh

Build output lives under .kinglet/ (see ADR 0014). Test helpers call ensure_build_stamp in tests/common.sh.

Repository layout

kinglet-self/
  core/           CLI entry (main.kl), AST printer, checker driver
  lexer/          Scanner, tokens, keywords
  parser/         AST, recursive-descent + Pratt parser
  checker/        Type checker
  compiler/       AST → bytecode (imports, match, builtins, …)
  tests/          Harness-driven suites (see tests/README.md)
  kinglet         Project build driver (`./kinglet build`)
  .kinglet/       Klos cache and build output (gitignored)
  kinglet.toml    Project manifest (`//` import paths, `[build]` section)
  SYNTAX.md       Syntax notes and self-host / bootstrap boundaries
  AGENT.md        Context for AI-assisted development

Module system: import { "//parser/ast.kl" } with file-stem namespaces; using ast { Expr }; for selective imports. See ADR 0011.

Testing

See tests/README.md for the full layout (decision 0012).

Suite	Command	What it checks
All	bash tests/run_all.sh	Gating suites + probe/builtin/differential snapshots
Harness (ad-hoc)	bash tests/harness/run.sh <cases/>	Directive-driven pipelines
Selfhost E2E	bash tests/exec/run.sh	compiler.kbc compile + run
Sema	bash tests/sema/run.sh	--check pass and fail cases
Differential	bash tests/differential/run.sh	bootstrap vs selfhost must match
Property	bash tests/property/run.sh	AST/token stability + fuzz-lite
Capability matrix	bash tests/probe/run_matrix.sh	28 language-feature probes (snapshot)
Builtin methods	bash tests/builtin_methods/run_matrix.sh	26 builtin methods (snapshot)

Authoritative self-host semantics — exec/, sema/, probe, and builtin matrices run through compiler.kbc. Bootstrap kinglet is the VM host; differential and regression also exercise the C++ compiler path.

Detailed write-ups:

• tests/README.md — suite index and harness guide
• tests/harness/directives.md — directive language
• tests/probe/README.md — feature capability matrix
• tests/builtin_methods/README.md — builtin method coverage, opcode reference, checker gaps

Current snapshot (2026-06-10)

Matrix	run✓	Notes
Feature probes (tests/probe)	28/28	Bootstrap aligned on same corpus (see differential)
Builtin methods	26/26 runtime	Checker 24/26; see builtin README for fix list

Documentation

Document	Purpose
SYNTAX.md	Syntax, operators, sh/bs differences
kinglet-lang/ADRs	Architecture decision records (design RFCs)
ADR 0003	Planned stdlib/ layout
AGENT.md	Conventions, commit style, bootstrap quirks
docs/ci.md	GitHub Actions CI/CD and local reproduction

Related repositories

Repository	Role
github.com/kinglet-lang/bootstrap	C++ bootstrap compiler + VM (reference implementation)
github.com/kinglet-lang/kinglet	Self-host compiler sources + tests (this repo)
github.com/kinglet-lang/ADRs	Architecture decision records (design RFCs)

License

MIT