Running Programs

Start With A Small Example

The normal first run is:

kira run examples/hello

On the current repo state, that prints:

geometry demo
20
12
30
25
hello
Color(r: 255, g: 0, b: 0)

Core Commands

Use these first:

kira run examples/hello
kira check examples/hello
kira tokens examples/hello
kira ast examples/hello

What they do:

run executes the default VM backend unless you choose another backend
check parses, resolves imports, prepares matching native libraries, runs autobinding when needed, and validates semantics
tokens dumps lexer tokens
ast dumps the parsed AST

The default VM path now prints richer runtime values than the earlier bootstrap subset, including named struct values.

Choose A Backend Explicitly

The CLI supports three execution targets:

kira run --backend vm examples/hello
kira run --backend llvm examples/callbacks
kira run --backend hybrid examples/hybrid_roundtrip

The repo currently proves all three paths:

VM: examples/hello, examples/arithmetic, examples/imports_demo, and similar subset programs
LLVM/native: native callbacks and Sokol proofs
hybrid: mixed @Runtime and @Native programs plus hybrid FFI tests

Today, the broadest print(...) surface lives on the VM/default execution path. Native and hybrid backends still have a narrower runtime print surface while their lowering/runtime support catches up.

For backend debugging, run also supports:

kira run --backend hybrid --trace-execution examples/hybrid_roundtrip

That debug-only flag writes trace lines to stderr so you can see VM/native/bridge transitions, callback entry/return flow, and print ownership while a mixed program runs.

Build Artifacts

build writes artifacts into generated/ by default:

kira build examples/hello
kira build --backend llvm examples/hello
kira build --backend hybrid examples/hybrid_roundtrip

Current output shapes:

Command	Primary output
`build`	`generated/<name>.kbc`
`build --backend llvm`	host executable plus native object file
`build --backend hybrid`	`generated/<name>.khm` plus `.kbc`, object file, and shared library sidecars

When To Use `zig build run -- ...`

If you are editing the CLI itself, use:

zig build run -- run examples/hello

That keeps you on the freshly rebuilt in-repo CLI instead of whatever launcher is currently on your PATH.

Native Library Imports And `check`

check is also the first cheap way to verify FFI setup.

For example:

kira check examples/sokol_triangle

That succeeds only after Kira has:

resolved the imported binding module name
found the matching manifest under a nearby native_libs/
resolved the native library for the host
generated the binding module when required

So check is a practical way to validate your native library description before you ask for a full native or hybrid build.