Docs / Developer documentation

Developer documentation

This section is for contributors working on the compiler, and for anyone who wants to understand Moth beyond using the language.

It provides a peek behind the curtain at how Moth works under the hood: the staged compiler pipeline, the memory model, and the standards the codebase is held to.

Explore the internals

• Compiler design: staged pipeline, task-reading matrix and cross-cutting contracts
• Memory management: reference semantics, borrow validation, lifetime regions, ownership and backend lowering
• Development standards: implementation style, test strategy and validation gates
• Design scope, public authority: accepted mechanisms, constraints and intentionally excluded complexity
• Compiler-facing language reference: bridge to the canonical language overview
• Progress matrix: current implementation status and known gaps
• Roadmap: planned work and design direction
• Repository index: quick module and file locator

Compiler flow

project files
    -> Stage 0: project structure and source discovery
    -> Stage 1: tokenization
    -> Stage 2: header parsing
    -> Stage 3: dependency sorting
    -> Stage 4: AST construction
    -> Stage 5: HIR generation
    -> Stage 6: borrow validation
    -> lifetime-region and escape validation
    -> backend-neutral memory requirements
    -> build-owned link planning, target partition and target validation
    -> target/profile-aware compiler-owned memory planning
    -> ValidatedMemoryPlan
    -> backend lowering
    -> output files

Design docs vs current support

Developer documentation describes accepted end-state architecture. Some pages define design that the compiler and backends are still converging on.

Use the progress matrix to see what is implemented, partial, experimental or still missing. Use the roadmap for sequencing and proposals not yet accepted as design.