The Basics

The repo's smallest Kira programs have a direct shape:

@Main
function main() {
    let left = 40;
    let right = 2;
    let total = left + right;
    print(total);
    return;
}

Source Files and Modules

Kira source lives in .kira files. The repo commonly uses:

• app/main.kira for an application's entry module
• sibling files such as Support.kira or UI.kira for imported modules
• nested module names such as bindings.callbacks

Imports use qualified names and may add an alias:

import Support as Support
import bindings.callbacks as callbacks

Comments

The current lexer documents single-line comments with //:

// generated by kira FFI autobinding for callbacks

This is the comment form that appears in generated bindings and is tokenized explicitly by the lexer.

The Entrypoint

Programs choose their entry function with @Main, not with a special function name.

Current semantic rules:

• exactly one function must be marked @Main
• @Main must not declare parameters
• duplicate or conflicting execution annotations are rejected

The fail corpus proves diagnostics for:

• missing @Main
• multiple @Main entrypoints
• duplicate @Main
• invalid @Main signatures

Top-Level Declarations

The current frontend recognizes these top-level declaration forms:

• import
• function
• class
• struct
• construct
• construct-defined forms such as Widget Card(...) { ... }

Those are the forms you see throughout the guide.

Local Bindings

Local declarations use let and var.

let total = left + right;
var monthLabel: String
var aspectRatio: Float = 1.0

The declaration model is explicit:

• var name = expression: infer the declared type from the initializer expression
• var name: SomeType: declare an uninitialized local of that type
• var name: SomeType = expression: require the initializer expression to already match the declared type

Kira prefers inference when the type is obvious, but it does not guess when the program is ambiguous:

@Main
function entry() {
    let value;
    return;
}

That fail case produces KSEM029 ("type inference is ambiguous").

Typed declarations without initializer expressions are valid, but they stay uninitialized until some later assignment gives them a value. Reading them earlier is rejected.

Annotated initializers are strict:

var ok: Float = 0.0
var wrong: Float = 0

The second form is rejected because the declared type is Float and the initializer expression is an integer literal.

Statement Style

The checked-in examples use both:

• semicolon-terminated statements
• newline-delimited statements

Both styles are accepted in the forms already exercised by the repo.

Current Status

The basics chapter mixes two real layers of Kira:

• declarations, names, annotations, and constructs belong to the frontend surface
• the fully proven runnable core is smaller and centers on @Main, functions, locals, direct calls, return, print, and the currently lowered expression subset