Nikaia Toolchain Architecture

How the crates in the Nikaia workspace stack up. The separation they implement is ADR-003: the language and the machinery that compiles it are two programs, and the interface between them is Rust source text.

High-Level Stack

graph TD
    A[User source .nika] -->|Input| B(Crate: nikaia)
    subgraph Frontend
        B -->|Parses| C{AST}
        C -->|Lowers| D[Rust source text]
    end
    D -->|Written out| E[Generated .rs]
    E -->|Invokes| F[System rustc]
    F -->|Produces| G[Binary executable]

    H(Crate: orchestrator) -.->|cache, manifest, cargo| B
    I(Crate: nikaia-std) -.->|linked into| G

Detailed Component Breakdown

1. The frontend and the CLI: crates/nikaia

• Role: everything that knows what Nikaia means.
• Responsibilities:
  • CLI: arguments via clap; nikaia build, nikaia run, nikaia lower-std, and nikaia lower, interpret and explain for a single file.
  • Parsing: winnow-grammar (and winnow) parse .nika sources into a Nikaia-specific AST — over bytes, not over Rust tokens (ADR-001 D2).
  • AST: the language constructs, in src/ast.
  • Checks: types, contracts, sync, provenance, statement ordering — src/check, src/contracts.
  • Lowering: src/emit turns the AST into Rust source text, in one pass, and writes a SourceMap beside it. It is the only code generator in the toolchain (ADR-004 D1).
  • Diagnostics: rustc --error-format=json read back and reported against the .nika line that caused it (ADR-300).
• Dependencies: orchestrator, winnow-grammar.

2. The manager: crates/orchestrator

• Role: the build machinery that is not Nikaia’s — the part a second language would reuse unchanged (ADR-003 D2).
• Responsibilities:
  • cache: the build-cache key, the content-addressed store and nikaia.lock (ADR-021).
  • project: nikaia.toml rendered to a Cargo.toml, cargo driven over it, and RUSTC_WORKSPACE_WRAPPER injected so that a .nika file on a rustc command line is lowered and a crate from crates.io is not (ADR-002 D1).
  • LanguageFrontend: the trait a frontend implements — source text in, Rust source text out, and nothing else crossing the line.

3. The standard library: crates/nikaia-std

• Role: what a generated program links: the runtime, fs, io, text, list, html, the CLI surface.
• Written in Nikaia where Stage 0 can lower it (ADR-014 D1), with the lowered .rs committed beside the .nika and regenerated by nikaia lower-std (ADR-002 D4). A project reaches it through a sysroot, not through a registry.

Data Flow Example

1. Input: let x = 5
2. Parser: ast::Stmt::Let { name: "x", value: LitInt(5), … }
3. Emitter: let x = 5; inside the generated fn main, plus the source map entry that points that line back at the .nika one.
4. rustc: compiles the file to machine code.

This site is open source. Improve this page.