From Moth source to a webpage

We'll follow a small Moth program from files on disk to a generated HTML page.

If you write Rust, you already know functions, enums, structs and ownership as a user. You may not know terms like intermediate representation, link plan or borrow validation yet.

Each term shows up when the example needs it and will be explained step by step.

These docs are focused on teaching rather than documenting the compiler's actual implemented behaviour.

The small example project we'll follow

The file structure

compiler_walkthrough/
├── config.moth
└── src/
    ├── @page.moth
    └── greeting.moth

The code

greeting.moth

greeting_prefix #= "Hello"

greet |name String| -> String:
    return [: [greeting_prefix], [name]!]
;

@page.moth

@greeting greet

visitor = "Priya"

[$html:
    <p>[greet(visitor)]</p>
]

The final fragment the series aims at:

<p>Hello, Priya!</p>

Priya never changes. The file names never change. The fragment never changes. Side examples may wander for a paragraph, then come back to this greeting.

What each stage hands the next

One checkpoint strip runs through every article:

project tree
-> command and config
-> canonical source graph
-> located tokens
-> prepared shells
-> bound interfaces and ordered declarations
-> typed AST and semantic identities
-> folded constants, generated requests and TIR handoff
-> structured diagnostics
-> validated HIR
-> borrow and optional-transfer side-table facts
-> lifetime-region and escape-validation facts
-> immutable module artefacts and fingerprints
-> entry assembly and reachable function union
-> project/link lifetime topology validation
-> deterministic target assignment
-> JavaScript and Wasm outputs
-> HTML, runtime assets and output manifest

Each article opens with the incoming representation and closes with the outgoing one. If a page jumps ahead, you have left the chronological route.

Entry Command and project bootstrap build, dev or check selects the builder, profile and tooling overlays.

Internal flow

Typed CLI inputs config.moth folding Capability surface

Stage 0 + preparation Source discovery and preparation Build the canonical source index while compiler-owned preparation exposes structural dependencies and file references.

Internal flow

Source index Tokenization Header syntax preparation File-reference worklist

Stages 2b-3 Interface binding and declaration order Once providers are ready, bind retained dependency syntax and topologically order local declarations.

Internal flow

Completed provider interfaces Interface binding Local ordering

Stage 4 AST semantics Resolve types, fold constants and templates, specialise static control flow and commit generated requests.

Internal flow

Type checking Constant folding TIR and templates

Stage 5 HIR lowering and validation Lower the active typed program into backend-neutral executable control flow.

Internal flow

Typed AST to HIR CFG and invariant validation Structured diagnostics

Stage 6 Borrow validation Prove legal shared and exclusive access, future use and optional transfer candidates.

Internal flow

Places and overlap Last-use facts

Analysis Lifetime topology Build allocation families, retention facts and backend-neutral lifetime requirements.

Internal flow

Allocation families Retained edges Intervals and frontiers

Boundary Immutable module artefacts Publish successful module semantics, generated sidecars, link facts and reuse fingerprints.

Link planning Entries and reachable unions Select active roots, instantiate project lifecycles and validate the complete linked topology.

Internal flow

Entry roots Reachability Complete lifetime topology

Physical planning Target and memory planning Partition functions, validate target contracts and produce one validated memory plan per physical variant.

Internal flow

Target affinity Target validation ValidatedMemoryPlan

Backends Backend lowering Lower each selected physical variant without reopening source semantics.

Output paths

JavaScript WebAssembly HTML runtime glue

Output HTML assembly and output ownership Assemble documents and runtime assets, validate output paths, write manifests and clean stale artefacts.

Each box links to the walkthrough page that expands that stage. Side branches show important internal work without lengthening the main pipeline.

Question: which step still looks like source, and which first looks like something a host can run?

Four owners you will meet again

Build system. Selects the command, discovers source, builds graphs, schedules modules, plans entries and writes files to disk.

Compiler frontend and analysis. Prepares syntax, binds interfaces, checks semantics, lowers HIR and validates access.

Artefact builder. Assembles selected compiler facts into an output plan for one kind of project, such as an HTML page.

Target backends. Lower validated functions and runtime needs into JavaScript, Wasm and glue.

A fact has one owner. Later stages consume that fact. They do not rebuild it from source text.

How to read the series

Read in order. The path groups ideas by time of appearance, not by internal crate name.

This landing page acts as article 00.

Status language on every page

Later articles label four kinds of claim:

Accepted design: architecture or language contract the authorities already chose
Current implementation: behaviour the progress matrix records today
Queued or active implementation: named roadmap work still landing
Deferred or outside scope: postponed on purpose, or rejected as a language shape

The series links the progress matrix and roadmap. It does not paste either document into the articles. Accepted architecture stays the main teaching path.

Where authority lives

docs/compiler-design-overview.md for compiler stages, identities, artefacts and validation
docs/build-system-design.md for commands, graphs, builders, linking and outputs
docs/src/developer-docs/language/overview.mtf for language surface
docs/src/developer-docs/memory-management/overview.mtf for reference semantics, borrow validation, lifetime regions, ownership and backend lowering
docs/src/docs/progress/@page.moth for what works today
docs/roadmap/roadmap.md for order and deferred design

Educational pages explain those authorities. They do not outrank them.

Next: what a compiler does between Priya's name and a paragraph on a page.