Materialization Model

Materialization turns a builder program into an artifact. It is one interpretation of the program, not the whole meaning of the builder.

The materialization view is useful because it keeps the executable plan visible before and after a derivation exists.

Plans

A plan is the materializable shape of the program. It records the steps that write files, run tools, transform outputs, and produce final artifacts. Plans let you inspect order and intent before asking Nix to build.

Materialization works by walking the program and building up a plan state as it goes. The plan state carries working bookkeeping, such as which tools and services have been declared so far, so that later steps can be checked against earlier ones.

From Plan State To Build Plan

When the walk finishes, the plan state is projected into the final build plan. This projection forgets the working bookkeeping and keeps what the artifact needs, which is the outputs, the derivation, and the runtime declarations the builder promised. The bookkeeping existed only to validate the build as it was assembled.

Tool References

Tool references connect command steps to packages. This matters because a plan should not rely on ambient commands from the user's shell. If a step runs gcc, the program should know which package provides gcc.

Generated Commands

Plan-view exposes command snippets so users can inspect what materialization will execute. Use this view for debugging. The builder API should still be expressed in domain terms rather than asking users to manage every command directly.

Derivation Outputs

Materialization returns derivations and output declarations. The result should match the outputs the builder promised earlier in the spec.

Runtime Artifacts

When the program declares runtime services or units, materialization carries those declarations alongside the derivation result. A builder can therefore produce both a store artifact and a runtime description from the same program.