# `mix nbpr.build`
[🔗](https://github.com/jimsynz/nbpr/blob/v0.2.0/lib/mix/tasks/nbpr.build.ex#L1)

Builds an NBPR package from source against the active Nerves system's
Buildroot tree, then packs the result into a canonical artefact tarball.

    mix nbpr.build NBPR.Jq [-o /output/dir]

Thin CLI wrapper around `NBPR.Buildroot.Builder.build!/3` — `mix nbpr.fetch`
uses the same orchestrator as a fallback when no prebuilt artefact is
published for the active (system, system_version, build_opts) tuple.

## Cache short-circuit

Before kicking off a fresh source-build, the task HEADs the package's
GHCR `{:ghcr, "ghcr.io/<owner>"}` site for the cache-key-derived tag.
On a hit it downloads the prebuilt tarball into the output directory
and skips the build entirely — the cache key encodes everything that
affects the artefact (package version, system, system version, build
opts), so a hit is by definition byte-identical to what we'd build.

Pass `--force` to bypass the cache check (useful for verifying the
build still works locally, or for re-publishing after a cache-key
collision investigation).

## Required environment

- `MIX_TARGET` set to a real Nerves target (not `:host`).
- `deps/nerves_system_br/` and `deps/<system>/` resolved (`mix deps.get`).
- Either Linux + inside `mix nerves.system.shell`, or `docker` on PATH
  (any host) — only needed when no cache hit is found.

## Flags

  * `-o`, `--output` — directory for the produced tarball.
    Defaults to `<build_path>/nbpr/`.
  * `--build-opts key=value,...` — explicit build options for the package.
    Defaults are read from the package's schema if omitted.
  * `--force` — skip the GHCR cache-hit check and always source-build.

---

*Consult [api-reference.md](api-reference.md) for complete listing*