Builds

A build is one run of your build code against a workspace, producing the targets you selected.

Starting one

bldr build                       # the workspace default targets
bldr build site                  # one member or target
bldr build '**[test]' --name "..."

The command attaches to the build and streams its progress. Ctrl-C stops the build; Ctrl-X leaves it running and detaches you.

Always pass --name. It is what bldr builds shows afterwards, and a sentence about why you built beats a UUID.

Post-build actions

Building produces content. Usually you want something done with it. Actions attach to the build, and naming one also selects its target, so bldr build --deploy site/staging is a complete command.

--export, --mount, --run and --deploy take a target filter over full target names (site/web, the member and then the target), with the same globs and brackets as the targets you build. Each acts only on its own sort of target — a broad filter skips the rest.

The path of an export or a mount is a template, so one filter can place many outputs: {0}, {1}, … insert what the filter's wildcards matched, and {key} a target's label. Every output needs a path of its own.

bldr build --export 'site/*:./out/{0}' --name "every site output"

Each action waits on its own target, so a slow target never holds up the export of a fast one, and a target that fails cancels only its own actions.

Every round re-runs every action against that round's output. The two that outlive a round update rather than accumulate: --run re-points the same run at the new build, and --mount re-points the existing mount in place, so something reading through the path sees the new tree rather than a gap.

Watching

bldr build --watch --name "live"

A watching build follows the workspace: every sync that changes its input triggers another round. It also follows edits to options.targets, so changing the default selection changes what the next round produces.

Managing them

bldr builds                       # list
bldr builds get <ID>              # one build's state and targets
bldr builds create --detach ...   # start one without attaching
bldr builds attach <ID>           # attach to a running one
bldr builds stop <ID>             # stop the work, keep the record
bldr builds remove <ID>           # drop the record

Detaching is worth knowing about for anything long: the build belongs to the node, not to your terminal, so closing the terminal does not end it.

When something fails

The failing task carries the error and a link to the log of the pod that produced it. bldr logs tail <ID> reads it. A build that failed keeps its record, so you can read it afterwards rather than re-running to see the error again.