Karkain for Visual Studio Code

Professional development environment for the Karkain programming language (.kark): syntax highlighting, karkain check Problems integration, build/run terminal workflows, karkain fmt formatting, and Karkain Language Server (karkain lsp) intelligence. This is an integration layer only — the compiler, runtime, formatter, test runner and language server live in the Karkain repository.

Requirements

Karkain 1.1.0 toolchain (karkain on PATH or karkain.compilerPath). Structured check diagnostics need --format=json (1.1.0+); older toolchains get raw-output fallback, never fabricated diagnostics.
VS Code 1.75+ (desktop; the toolchain spawns native processes).
A C compiler (GCC/Clang/MSVC) for build/run; GDB + the Microsoft C/C++ extension for native debugging.

Install (local `.vsix`)

npm install
npm run package
code --install-extension karkain-0.9.0.vsix

Release builds are attached to GitHub Releases (see docs/RELEASE.md); the Marketplace step is a separate, manual owner decision.

Commands

Karkain: Check File · Build File · Run File · Clean · Test · Debug File · Format Document · Show Environment · Select Toolchain · Select Target · Restart Language Server

Targets

Karkain: Select Target lists the matrix reported by karkain target (platform triples plus compute targets with their real maturity labels). The status bar shows the selection; build/run append --target. Debugging always uses a host build. Foreign run is refused by the toolchain, and missing cross-linkers fail loudly — both surface in the terminal.

Testing

Testing view lists *_test.kark files and their test_* functions (discovered via document symbols). Run files or individual tests; results, assertion output and the totals line appear under each test and in the Karkain Test channel. Test files cannot be debugged (they do not link).

Tasks

Terminal → Run Task offers karkain: build/check/run/clean for the active .kark file (build is the default build task with the $gcc matcher; clean runs in the karkain.toml project root when detected).

Debugging

Requires GDB and the Microsoft C/C++ extension (cppdbg). Karkain: Debug File builds the active file with karkain build -g and launches it under GDB — breakpoints, stepping, variables, call stack, watch and evaluate all come from GDB. For manual launch.json setup, copy templates/launch.json and templates/tasks.json to your workspace .vscode/ and press F5. karkain.debuggerPath selects the GDB binary. Test files cannot be debugged (they have no main and do not link).

Settings

karkain.compilerPath (default karkain) · karkain.debuggerPath (default gdb) · karkain.formatOnSave (default false) · karkain.target (default empty = host default).

Known limitations (Phase 9)

karkain fmt whole-document formatting requires Karkain 1.1.0+.
Semantic features follow the server: rename, references, code actions and workspace symbols are absent from karkain lsp and are not faked.
GPU/NPU/Quantum targets are model-only or research-grade per the toolchain; only cpu/simd/wasm32-wasi/native triples execute today.
Desktop VS Code only; vscode.dev is unsupported (native toolchain).

Development

npm install
npm run typecheck
npm run lint
npm run format:check
npm run test:unit
npm run package
# manual gates, need a 1.1.0+ binary (not in CI):
npm run test:lsp-smoke -- /path/to/karkain
npm run test:toolchain-smoke -- /path/to/karkain

Troubleshooting

cannot locate src/compiler (exit 6): a source-built karkain needs its compiler tree — set KARKAIN_KCC to the Karkain source directory or work inside it. Release-installed toolchains do not need this.
Karkain: could not start the karkain executable: set karkain.compilerPath to the binary or put it on PATH, then Karkain: Show Environment to verify.

See docs/KARKAIN-INSPECTION.md (toolchain truth), docs/INTEGRATION-BOUNDARY.md (capability claims), docs/ARCHITECTURE.md and docs/ROADMAP.md.

License

MIT — see LICENSE.

Karkain Language Tools

Karkain