How Luce becomes a program

Luce is not a syntax wrapped around a black box. It is a chain of explicit representations, each with one job, ending in native machine code and one shared runtime.

The whole system in one sentence

Source becomes tokens, syntax, checked meaning, typed instructions, LLVM IR, an object, and finally a native artifact. Dynamic behavior—ARC, containers, text, resources, workers, and traps—has one implementation beneath the native path and the test oracle.

The path from text to instructions

Every box is a boundary in the repository. Click one to see what it accepts, what it produces, which decisions belong there, and which decisions are forbidden from leaking into it.

Front end → native backendEach arrow crosses a typed seam

01Sourcebytes → trusted files 02Lextext → layout tokens 03Parsetokens → untyped AST 04SemanticsAST → checked HIR 05–06HIR → MIRmeaning → typed blocks 07OptimizeMIR → smaller MIR 08CodegenMIR → LLVM object 09Link & runobject → machine code

The compiler driver stops after verified, optimized MIR. Artifact creation deliberately begins from that same seam, whether the result will be a relocatable object, a loadable .lc library, or a standalone executable.

compile.zig luce.zig PIPELINE.md

One shipping path, one test oracle

There is no VM, bytecode engine, JIT, or runtime fallback. Users run LLVM-generated machine code. Tests also feed the same MIR to an independent interpreter, then compare the two executions. That interpreter ships in neither luce nor loom.

One program, two observationsThe runtime is shared; dispatch is independent

Verified MIRone typed program

LLVM paththe engine that ships

Native resultoutput, trap, world, leaks

Interpretertest-only dispatch loop

Oracle resultthe same observable record

machine-code pathZig implementation

The comparison includes printed bytes, raised error, trap code and message, call trace, the host world left behind, and the live-object census. Plausible output is not enough if one path leaked an object or touched the wrong file.

Explore by system

CompilerLoading, lexing, parsing, meaning, IR, optimization, and LLVM lowering. Language featuresEvery user-visible rule traced through representation, compile-time checks, and runtime behavior. RuntimeARC, heap objects, text, containers, resources, workers, arithmetic, and traps. LibraryWhat is ordinary Luce source, what is a compiler primitive, and what must be Zig. ExecutionObjects, linking, artifact identity, loading, luce_main, and the oracle. DecisionsThe invariants, explicit refusals, version seams, and true cost of changing the language.

Three implementation territories

The syntax alone does not tell you where a feature lives. This atlas labels three territories consistently:

Luce source

Standard modules, packages, the editor, examples, and application logic written in the language itself.

Zig implementation

The compiler, verifier, runtime, host adapters, loader, linker orchestration, and test oracle.

Native machinery

LLVM optimization, emitted object code, the platform linker, dynamic loader, and operating-system services.

Open the complete Luce ↔ Zig ownership map →

Current code, not a museum

This site describes the repository as it exists now. Its footer values—MIR format 62, host ABI 29, release 0.18—are inserted from the actual source during every build. Source badges are checked paths, not decorative citations.

For writing Luce, use luce.luciaos.com. Its examples are compiled and run. This site answers the different question: what engineering makes that behavior true?