bldr build

bldr build

Create a build and watch it live until it finishes.

The build is attached: pressing Ctrl-C aborts it, Ctrl-X detaches (leaving it running on the node). The input is the workspace discovered from the current directory (or -W <PATH>), or an explicit --input <CID>. For listing / managing builds, see bldr builds.

bldr [BLDR FLAGS] build [BUILD FLAGS] [FILTER]...

<FILTER>

What to build: target filters, additive. A plain path is that target and everything inside it (bldr/daemon); a glob is matched as written ('bldr/*[test]', '**[deployment]', '**/lsp[bldr.runnable.lsp=v1]' — quote them, or the shell expands them first). <MEMBER>:<ITEM> builds a single registered item's CID and takes no other filters. Omitted → what --export/--mount/--deploy/--run name, or with none of those, the workspace's default filters (options.targets). These are real positionals, so flags like --export work in any position

May be given more than once.

-W, --workspace <PATH>

Target workspace directory. Defaults to the one discovered by walking up from the current directory

--input <CID>

Build a fixed, explicit BuildInput CID (standalone, no workspace)

--watch

Follow the workspace BuildInput, rebuilding incrementally on every sync (workspace builds only)

Defaults to false.

--fetch-only

Only sync the workspace members (streaming their fetch progress) without running the build controller. Replaces the old ws sync-members

Defaults to false.

--refetch

Force all workspace members to bypass the sync cache and re-call their content providers, even if the member's resolved spec hasn't changed. Useful when upstream content changed without the spec changing (e.g. a mutable container tag). Does not affect the function-invocation cache

Defaults to false.

--ref <NAME>

Store the output under a local ref. Repeatable

May be given more than once.

--mount <FILTER:POINT>

FUSE-mount outputs, re-pointed at every rebuild. Repeatable.

Format: FILTER:POINT — the same shape as --export: FILTER a target filter over full target names selecting output directories or images, POINT a path template for where to serve each. Export copies those trees out; mount serves them in place. A bare POINT mounts the whole output.

May be given more than once.

--run <FILTER>

Keep runnables running from this build's output, hot-swapping them on every rebuild. Repeatable.

FILTER is a target filter over full target names, in the grammar of the positional filters (bldr/vm-hello/hello, 'bldr/ui/*'). It acts on runnables only: other targets under it are skipped, a [kind] of another sort is refused, and matching no runnable fails the build. It also selects what it matches, so no positional is needed.

May be given more than once.

--export <FILTER:PATH>

Materialise outputs of the build to local paths. Repeatable.

Format: FILTER:PATH. FILTER is a target filter over full target names selecting output directories or images (other targets under it are skipped); it also selects them for building. PATH is a template: {0}, {1}, … insert what the filter's wildcards matched, numbered left to right from 0; {key} inserts the target's label key; {{/}} are literal braces. Every selected target must land on a path of its own — e.g. 'bldr/packaging/deb/*-vm-*:/var/tmp/debs/{0}/{1}'.

May be given more than once.

--deploy <FILTER>

Invoke deployments after the build. Repeatable.

FILTER is a target filter over full target names ('bldr/packaging/k8s-test/**[bldr.matrix.arch=amd64]'). It acts on deployments only: other targets under it are skipped, a [kind] of another sort is refused, and matching no deployment fails the build. It also selects what it matches, so no positional is needed.

May be given more than once.

--name <NAME>

Name this build, so it is identifiable in bldr builds and the console instead of appearing as one more UUID. Travels as the label bldr.name=<NAME>

--label <KEY=VALUE>

Attach a label KEY=VALUE to the build (repeatable). --name is the shorthand for --label bldr.name=…

May be given more than once.

--keep

Do not tie the build to this command: it keeps running on the node (with the pods it created) however the command ends — finished, interrupted, timed out or killed. Only Ctrl-C in the live view stops it. The build's record is retained either way — this only controls whether its work is stopped

Defaults to false.

--no-cache

Re-run every function instead of using cached results.

Skips the invocation-cache lookup for this build only. Fresh results are still stored, and a fresh result replaces a differing one already stored for the same input, so later builds are served what this one produced. Unlike bldr cache clear, nothing shared is deleted.

Pods still mount their cache volumes as they are; add --no-cache-read to run them over empty ones.

Defaults to false.

--cache-read <GLOB>

Restrict which cache volumes this build may read, by glob on the volume name (cargo-*, bldr/daemon/**). Repeatable; omitted → all

May be given more than once.

--cache-write <GLOB>

Restrict which cache volumes this build may write back, same syntax. Repeatable; omitted → all

May be given more than once.

--no-cache-read

Read no cache volume: a pod that runs gets every one mounted empty.

This alone does not make a pod run: a pod whose result is in the invocation cache is still replayed, and mounts nothing. Pass --no-cache as well to run everything cold — that pair is what answers "is the cache lying to me".

A volume mounted empty is also not written back: the workspace's volumes stay exactly as they were, so a cold run diagnoses a bad volume and does not repair it.

Defaults to false.

--no-cache-write

Write no cache volume back: use them, leave them exactly as found. The read-only mode for an experiment, a bisect, or a branch you do not want poisoning the shared caches

Defaults to false.

--distribution <DISTRIBUTION>

Where this build's invocations may execute.

local-except-unsupported (the default) runs what this node has and shops the rest out. local-only never leaves. local-except-queued prefers this node while it can start immediately, and otherwise lets a peer race it. non-local insists on a peer for everything, which is how you find out whether the distributed path actually works.

A cache hit is not an execution and is served locally under every one of them.

Defaults to local-except-unsupported.

--profile

CPU-profile every pod this build starts.

Each profile is sealed on its pod (bldr pod profile <id>; the console renders a flamegraph), and the build keeps its pods until the build is removed — so bldr pod list --build <id> finds them afterwards.

Worth pairing with --no-cache: a pod whose result is already in the invocation cache does not run, and a pod that does not run cannot be sampled. Needs the node's bldr-perf-helper to hold CAP_PERFMON; without it the build is unaffected and reports no profiles.

Defaults to false.

--no-targets

Build nothing: resolve the workspace and its build graph, then stop.

Not the same as naming no target, which means "no opinion" and falls through to the workspace's targets option. This says the opposite — force nothing at all.

The build code still runs, so a type error in it still fails the build and the declared target list is still produced. That makes this the cheapest way to ask "does my build code work, and what does it declare?" without building any of it. It is what an editor session uses.

Defaults to false.

-o, --option <KEY=VALUE>

Override a workspace option for this build only (repeatable): -o profile=release, -o targets='[app, bldr/ui]'. VALUE is read as YAML, exactly as bldr ws set reads it, and replaces the workspace's value of KEY for this build; bldr-workspace.yml is not touched. The overrides are recorded on the build (bldr builds get), so a build is never a mystery about what it was given. build_controller cannot be overridden

May be given more than once.