toolchain/build

Everything a build driver configures, plus the entries it adds.

A driver mutates this in place. It describes in code what a vader.json declares: the entries, the module search roots, the assets. What the command asked (a build, a check or a run, the profile, --entry) comes from args and is not the driver's to change.

What a drained messages() leaves behind.

One module a driver asked the compiler to generate.

One event the compiler hands a build driver.

Top-level declarations of one module, after typecheck.

The declarations are the compiler's own nodes, not copies: reading a field costs nothing, and a span taken from one anchors a diagnostic directly in the user's source. This is why a driver runs natively rather than through the comptime VM; see the plan referenced in context.vader.

Each declaration is delivered exactly ONCE per entry. A module the driver generated into is therefore delivered a second time carrying only the generated declarations, never the ones already seen, so a rule applied here fires once however many generation rounds that entry takes.

The pipeline crossed a stage boundary.

The build finished; no further message follows.

Carries the exit code, since a stream has no return value: a driver that drains to the end reads its build's outcome here.

Where the pipeline is, ordered as the stages run.

Every variant has an emission site: draining messages() walks the whole build, so there is no reserved half of this enum. BeforeEmit is the one to know about: it is the last point at which leaving the loop produces nothing, which is how a driver that only wants to observe declines to build.

Behaviour plugged into a build, told each message of the stream in order. Every member does nothing unless the plugin overrides it.

Build a context carrying the defaults a driver would otherwise restate.

The project root comes from args, not from the process working directory: the stdlib exposes no cwd() (std/env has only get_env, and the C runtime no getcwd), so threading it is the only way a driver can know where it is. The compiler passes the root it resolved in the request; invoked bare, the root is left empty rather than guessed.

What the command running the driver asks of it. Only .Build writes outputs: vader check (.Check), run, dump, lint and graph (.Prepare) and vader info or the language server (.Describe) run the driver and link nothing, emit_native returning 0 all the same. A step after the build, installing or packaging, checks ctx.mode() == .Build.

Add a program for the build to compile, as a key of entries does in a vader.json.

Order is preserved and load-bearing: it fixes the order modules are read, and therefore symbol-id assignment, which is what keeps a build byte-identical across runs.

Add a file or folder for a build to copy beside the binaries, as assets does in a vader.json. It lands under the same relative path, and a folder is copied with everything it holds.

Report a problem from the driver, anchored in the user's source.

Accumulates; the end of the stream or the driver's exit prints, and an error among the reports makes the build's code 1. The driver describes the problem and the registry owns the code (H6004): a project's lint rules should never have to allocate diagnostic ids, and every driver report stays greppable under one code.

Pass the tightest span the user can act on: a decl's name_span rather than its span, a field rather than the struct holding it.

Reports accumulated so far, in order.

Drive the compilation and yield what the pipeline produces.

Nothing compiles until the first message is pulled, so a driver configures the context first and iterates second. Each entry is run through the front end (load → resolve + typecheck → comptime), yielding one TypecheckedMessage per module, then a PhaseMessage, and finally one CompleteMessage for the whole run.

Every typed module is yielded, the stdlib included: a driver that only cares about its own code filters on module_name. Reporting the full set is the honest default: which modules are "the project" is the driver's policy, not this function's.

Every declaration is delivered exactly ONCE per entry, however many generation rounds that entry takes, see TypecheckedMessage. A module with nothing new is not yielded at all. The "once" is per ENTRY, not per build: two entries sharing a module both report it, which is already true of the stdlib.

Batched per file rather than streamed per declaration: Vader is single-threaded here, so the compiler fills a phase and hands it over. The loop shape is the same either way, and the order is specified rather than dependent on scheduling, which is what keeps a driven build reproducible.

A driver that generates code makes the stream LOOP: the phases from Typechecked to BeforeEmit repeat once per generation round, and the back end runs only after the last one. Declarations are still delivered once each (see emit_module), so an observing driver cannot tell the difference.

What the command asked shapes the stream: --entry narrows the entries to one; a check lowers after the last generation round and links nothing; the preparation of a run writes the project for the CLI and stops after the last generation round. A build writes each binary to build/<profile>-<target>/<name>, or to --out for its one entry, copies the assets beside them, and stops at the first entry that fails. Every mode writes the generated modules.

The plugins use received hear each message first, in that order (see BuildPlugin). The end of the stream prints the diagnostics not printed yet, the driver's reports among them, and an error among them makes the build's code 1 even when every entry built.

The exit code of a driver whose build returned code, once every context it made has printed what it still holds.

The entry vader build writes beside build.vader calls it; a driver does not. It is what prints the reports, and fails the build on an error among them, when the driver left messages() before its end or reported once the build was over.

Compile the entries into what the command asks: native binaries unless --emit names their C or their text bytecode.

This is what makes a driver a build system rather than an observer. Each entry is compiled to build/<profile>-<target>/<name> under the project, or to --out when one entry is built.

Front-end and lowering diagnostics are accumulated onto the context, so they interleave with the driver's own reports in the order they happened, and the end of the stream prints them all at once.

Compile the entries to C, without linking.

The counterpart of emit_native for a driver that wants the source: to post-process it, to hand it to another toolchain, or just to look. Mirrors --target=c.

Queue a module for the compiler to generate.

The driver writes text; the compiler owns the file. Call it as many times as you like on the same name: a module is a folder, so the emissions stack into it, and re-emitting identical text is a no-op. What you must NOT do is emit two different declarations of one symbol: that is T3053, reported against the generated files like any other duplicate.

Nothing is written until the round ends: the driver observes, emits, and the compiler flushes once the stream reaches BeforeEmit. The next round's front end then sees the new modules, and their declarations come back through messages(), which is what makes transitive generation work without a mechanism of its own.

Files written for the generated modules so far, in the order they landed.

The set is authoritative for the build that produced it: the sweep runs first, so every path listed here was written by this run.

File name for a generated module: <leaf>_<content hash>.vader.

Content-addressed on purpose, see this file's header. The hash is over the FINAL file text, banner and header included, so "same file, same path" holds without qualification.

Render a generated module's file: banner, module header, then the driver's text.

The compiler writes the header rather than trusting the driver's, so the declared module and the folder it lives in cannot drift apart: a mismatch would surface as R2020 against machine-written code.

Root the generated tree lives under, as a path.

Write every queued emission, and report which modules gained a file.

The return value is the round loop's fixed-point test: an empty list means this round changed nothing on disk, so running the front end again would see exactly the same files. A path that already exists is skipped: it holds the same content by construction, the name being its hash.

Delete the generated files of an earlier build, before this one starts.

Mandatory rather than tidy: file names are content hashes, so a module whose text CHANGED leaves its previous file in place: in the same folder, where it still compiles, and its declarations collide with the new ones. Sweeping first is also what keeps a renamed or withdrawn module from resolving forever on the machine that generated it while failing on a fresh clone.

Only files starting with GENERATED_BANNER are removed. That is the whole safety argument for a recursive delete driven by a driver-supplied path: a generated_root aimed at real sources destroys nothing. Directories are left behind: the stdlib has no remove_dir, and an empty folder declares no module, so nothing resolves through it.

Run the driver a vader.json stands for, as the CLI does for a project folder described by one: the counterpart of a build.vader's build.

It declares what vader eject writes into a build.vader, search roots included, so that the two describe the project alike. The build itself does not depend on the roots it declares: the loader reads them from the vader.json, which it consults first.

Render a phase as the name a driver would print in a log line.

Plug plugin into the build, after the plugins plugged before it.

Read when the stream starts, as the rest of the configuration is: a plugin plugged once messages() has been pulled waits for the next build.

Where generated modules land, relative to the project root.

The resolver's own constant, restated here so a driver reading this contract does not have to reach into vader/front/resolver for it, and so there is exactly one string. Gitignored by convention (build/ already is): the generated tree is a build artefact, reproducible from the driver plus the sources it reads.

First line of every generated file, and the sweep's whole safety argument.

sweep_generated deletes a .vader file only when it starts with this, so a generated_root mistakenly pointed at hand-written sources destroys nothing.

Rounds of generation allowed before the build gives up.

A round is one full front end, so this is a real cost, not a formality: a driver that keeps emitting new text every round is looping, and the alternative to a cap is a build that never ends and says nothing. Eight is far above any legitimate depth: transitive derivation settles in two or three.