Getting Started

Kira is a compiler and bootstrap toolchain that is trying to keep a few boundaries clear:

• readable source comes first
• inference is welcome, but only when it is unambiguous
• library and framework behavior should live in Kira code when possible
• the Zig implementation should provide language mechanisms, runtime machinery, and build orchestration without hardcoding every high-level library feature

Kira's Current Shape

In this repository, Kira is not only a parser or an early language sketch. It already includes:

• kira_source, kira_lexer, kira_parser, kira_semantics, and kira_ir
• kira_bytecode and kira_vm_runtime for VM execution
• kira_llvm_backend and kira_native_bridge for native output
• kira_hybrid_runtime and kira_hybrid_definition for mixed runtime/native execution
• kira_build, kira_toolchain, kira_bootstrapper, and kira_cli for packaging and command flow
• a first real FFI system based on per-library TOML manifests and generated Kira bindings

What Lives In Kira vs Zig

Today the repo draws this line:

• Zig owns the compiler pipeline, runtime plumbing, toolchain management, native linking, and generated binding pipeline.
• Kira source owns the app code, generated bindings, construct-defined library shapes, and higher-level patterns built on top of the language surface.

This matters most in the frontend:

• the compiler understands constructs, annotations, builder/content blocks, lifecycle hooks, and namespaced references
• that does not mean the Zig implementation is hardcoding a full UI framework
• examples like examples/complex_language_showcase and examples/ui_library show the intended split: the language machinery is in the compiler, while framework behavior stays library-side

Project Status

Kira currently has two important truths at once:

1. The frontend understands more than the executable backends lower today.
2. The executable subset is already real enough to run VM, LLVM/native, hybrid, callbacks, and Sokol proof programs.

That is why the docs separate:

• frontend/reference material
• runnable backend behavior

Read The Basics next if you want the exact boundary between the broader frontend surface and today's runnable subset.