# Build


`plan` validates a sequence of `BuildStep` records via
`fx.pipeline.run` (reader/error/acc effects). `materialize` lowers
a validated plan to a `pkgs.runCommand` derivation; shell
generation is pure and tested inline.

## `materialize`

_materialize: convert a validated `BuildPlan` into a `pkgs.runCommand` derivation; copies sources, scopes per-step env vars, runs steps under `set -euo pipefail`._

```
materialize : { pkgs, plan, native ? [] } -> Derivation
```

Materialize a validated `BuildPlan` into a derivation.

Converts the eval-time plan (validated by `fx.build.plan`) into a
`pkgs.runCommand` derivation. Sources are copied into a working
directory, per-step environment variables are scoped, and steps
execute sequentially under `set -euo pipefail`.

The `plan` argument is the `.plan` field from `fx.build.plan`'s output.
Shell generation helpers (`mkStepScript`, `mkSourceSetup`,
`mkBuildScript`) are pure functions tested inline.

## `plan`

_plan: validate build steps against `BuildStep`, filter by `when` predicates against reader context, and collect errors/warnings without throwing._

```
plan : { name, steps, sources ? {}, context ? {} } -> { plan : BuildPlan, errors : [Err], warnings : [Warn], typeErrors : [Err] }
```

Validate and process build steps into a `BuildPlan`.

Runs an eval-time pipeline that validates each step against
`BuildStep`, filters steps by `when` predicates using reader
context, and collects all errors without throwing.

## Sub-namespaces

- [`types`](/nix-effects/core-api/build/types)

## Source

- [`src/build/materialize.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/build/materialize.nix)
- [`src/build/plan.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/build/plan.nix)
- [`src/build/types.nix`](https://github.com/kleisli-io/nix-effects/blob/main/src/build/types.nix)