# NBPR v0.2.1 - Table of Contents

> Nerves Binary Package Repository — library underpinning :nbpr_* packages

## Pages

- [nbpr](readme.md)
- [Contributing to NBPR](contributing.md)

- Tutorials
  - [Getting started with NBPR](getting-started.md)

- How-to guides
  - [How to add a Buildroot package to NBPR](add-a-buildroot-package.md)

- Reference
  - [Catalogue](catalogue.md)

- Explanation
  - [Why NBPR exists](why-nbpr.md)
  - [How NBPR composes with Buildroot](packaging-model.md)

## Modules

- [NBPR](NBPR.md): Nerves Binary Package Repository — the library underpinning every `:nbpr_*` Hex package.
- [NBPR.Application](NBPR.Application.md): Sets up `PATH`, `LD_LIBRARY_PATH`, and any package-declared `runtime_env` so
external programs spawned by the BEAM can find every loaded nbpr package's
binaries, shared libraries, and runtime resources.
- [NBPR.Artifact](NBPR.Artifact.md): Cache-key, naming, and on-disk layout for NBPR package artefacts.
- [NBPR.Artifact.Cache](NBPR.Artifact.Cache.md): On-disk cache for NBPR package artefacts.
- [NBPR.Artifact.Fetcher](NBPR.Artifact.Fetcher.md): Orchestrates the fetch path.
- [NBPR.Artifact.LibCheck](NBPR.Artifact.LibCheck.md): Firmware-time shared-library resolution check.
- [NBPR.Artifact.Resolver](NBPR.Artifact.Resolver.md): Behaviour for nbpr artefact resolvers.
- [NBPR.Artifact.Resolvers.GHCR](NBPR.Artifact.Resolvers.GHCR.md): Resolver for `{:ghcr, "ghcr.io/<owner>"}` site specs.
- [NBPR.Artifact.Resolvers.GitHubReleases](NBPR.Artifact.Resolvers.GitHubReleases.md): Resolver for `{:github_releases, "owner/repo"}` site specs.
- [NBPR.BrPackage](NBPR.BrPackage.md): The macro every NBPR package uses.
- [NBPR.Buildroot](NBPR.Buildroot.md): Discovery helpers for building nbpr packages against the user's pinned
Buildroot tree.
- [NBPR.Buildroot.Backend](NBPR.Buildroot.Backend.md): Behaviour for the different ways NBPR can produce a per-package Buildroot
artefact.
- [NBPR.Buildroot.Backend.Container](NBPR.Buildroot.Backend.Container.md): Shared runner for the container-based backends (`NBPR.Buildroot.Backend.Docker`,
`NBPR.Buildroot.Backend.Podman`, and future CLI-compatible runtimes).
- [NBPR.Buildroot.Backend.Docker](NBPR.Buildroot.Backend.Docker.md): Buildroot backend that runs the build inside Docker.
- [NBPR.Buildroot.Backend.Podman](NBPR.Buildroot.Backend.Podman.md): Buildroot backend that runs the build inside Podman.
- [NBPR.Buildroot.Backend.Shell](NBPR.Buildroot.Backend.Shell.md): Buildroot backend that runs `make` natively on the host.
- [NBPR.Buildroot.Build](NBPR.Buildroot.Build.md): Drives a per-package Buildroot build.
- [NBPR.Buildroot.Builder](NBPR.Buildroot.Builder.md): Source-builds an NBPR package artefact tarball end-to-end.
- [NBPR.Buildroot.Defconfig](NBPR.Buildroot.Defconfig.md): Generates a per-build Buildroot defconfig that layers nbpr-specific
settings on top of the active Nerves system's defconfig.
- [NBPR.Buildroot.FilesList](NBPR.Buildroot.FilesList.md): Reads Buildroot's per-package `.files-list.txt` / `.files-list-staging.txt`
and copies only the listed files (with a runtime-only filter) out of a
per-package merged sysroot.
- [NBPR.Buildroot.Finalize](NBPR.Buildroot.Finalize.md): Applies Buildroot's `target-finalize` cleanup to a harvested per-package
target tree.
- [NBPR.Buildroot.Harvest](NBPR.Buildroot.Harvest.md): Locates per-package Buildroot output and packages it as an
`NBPR.Pack.sources()` map for hand-off to `NBPR.Pack.pack!/3`.
- [NBPR.Buildroot.Package](NBPR.Buildroot.Package.md): Reads metadata for a Buildroot mainline package from a cached, extracted
BR tree. Used by `mix nbpr.new` so the scaffolded `mix.exs` and module
arrive pre-populated with version, licences, homepage, and a starter
description sourced from BR itself rather than left as `# TODO` stubs.
- [NBPR.Buildroot.Source](NBPR.Buildroot.Source.md): Manages the cached Buildroot source tree.
- [NBPR.Buildroot.SystemSource](NBPR.Buildroot.SystemSource.md): Resolves a path to the full source tree of an active Nerves system,
fetching from GitHub when the user has the Hex tarball (which deliberately
omits `Config.in` and `patches/`).
- [NBPR.Elf](NBPR.Elf.md): Minimal ELF introspection: reads a binary's `DT_NEEDED` shared-library
dependencies via `readelf`.
- [NBPR.Inspector](NBPR.Inspector.md): Pretty-printer for `NBPR.Package` metadata.
- [NBPR.OCI.Push](NBPR.OCI.Push.md): Pure-Elixir OCI artefact push to ghcr.io.
- [NBPR.Pack](NBPR.Pack.md): Produces a canonical NBPR artefact tarball from a directory of built files.
- [NBPR.Package](NBPR.Package.md): Metadata struct describing an NBPR package.
- [NBPR.Package.Daemon](NBPR.Package.Daemon.md): Metadata struct for a single daemon declared by an NBPR package.
- [NBPR.Runtime](NBPR.Runtime.md): Runtime helpers for Application-bearing NBPR packages.
- [NBPR.Spdx](NBPR.Spdx.md): SPDX licence-list cache and validation.

## Mix Tasks

- [mix nbpr.cache](Mix.Tasks.Nbpr.Cache.md): Introspect and garbage-collect the extracted-artefact cache that
`mix nbpr.fetch`/`mix nbpr.build` populate under
`$NERVES_ARTIFACTS_DIR/nbpr/` (defaulting to `~/.local/share/nerves/nbpr/`).
- [mix nbpr.catalogue](Mix.Tasks.Nbpr.Catalogue.md): Refreshes `docs/reference/catalogue.md` by globbing the workspace's
`packages/nbpr_*/` directories and reading each package's `mix.exs`
for the version and description.

- Mix tasks
  - [mix nbpr.build](Mix.Tasks.Nbpr.Build.md): 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.fetch](Mix.Tasks.Nbpr.Fetch.md): Walks the user's loaded applications for nbpr packages, fetches each one's
artefact tarball for the active Nerves system (if not already cached), and
copies the artefact's `target/` contents into the package's `priv/` so it
ships as part of the OTP release.
  - [mix nbpr.inspect](Mix.Tasks.Nbpr.Inspect.md): Pretty-prints the `NBPR.Package` metadata struct for the given module.
  - [mix nbpr.install](Mix.Tasks.Nbpr.Install.md): Installs and configures NBPR in a Nerves project so it can consume
binary packages from the `nbpr` Hex organisation.
  - [mix nbpr.matrix](Mix.Tasks.Nbpr.Matrix.md): Generates the prebuild matrix for CI: every combination of an `nbpr_*`
package under `packages/` with a target system declared in the workspace
`mix.exs` `@prebuild_systems` map.
  - [mix nbpr.new](Mix.Tasks.Nbpr.New.md): Scaffolds a new NBPR package under `./packages/nbpr_<name>/`.
  - [mix nbpr.pack](Mix.Tasks.Nbpr.Pack.md): Produces a canonical nbpr artefact tarball from already-built files on disk.
  - [mix nbpr.publish](Mix.Tasks.Nbpr.Publish.md): Uploads a tarball produced by `mix nbpr.pack` to the first supported backend
declared in the package's `artifact_sites:`.
  - [mix nbpr.releasable](Mix.Tasks.Nbpr.Releasable.md): Diffs each package's `mix.exs` `@version` against the latest version
published to the `nbpr` Hex organisation, returning the topo-sorted
list of packages that need a fresh release tag.

