Repository navigation
Package Store
The package store is a single repository of NFB packages that anyone can add to with a pull request. NFB reads it through a metadata.json that is published to GitHub Pages on every merge.
| Command | What it does |
|---|---|
nfb search [term] |
Lists packages, optionally only those matching term
|
nfb install llvm |
Adds the latest version to the manifest, or moves to it if it's already there |
nfb install llvm@19.1.0 |
Adds an exact version |
nfb remove llvm |
Removes the package from the manifest |
nfb install adds a dependency and updates nfb.lock, it does not build anything. Comments and layout in the manifest are kept.
[[dependency]]
name = "llvm"
source = "store"
version = "19.1.0"Versions are always exact, there are no ranges. nfb update re-resolves pins, but it never changes a version. To move to a newer version, run nfb install again.
Once nfb.lock has a package, builds no longer need the store to be reachable.
NFB_STORE overrides the URL of metadata.json, for forks and self-hosting.
A package is a folder in packages/ with two files. Nothing else is allowed in it, so sources come from [source] or command.
packages/llvm/package.nfb.toml
packages/llvm/meta.toml
# meta.toml
description = "A compiler toolchain" # required
license = "Apache-2.0"
homepage = "https://llvm.org"
platforms = ["linux/amd64"] # the default, shown by nfb install when it doesn't matchPrefer official prebuilt archives where they exist, as the store holds recipes and not binaries. Everyone who uses a package that compiles from source has to wait for it.
Run nfb pin next to package.nfb.toml to download [source] and write its sha256, it is not meant to be written by hand.
The rules for a package are:
- The folder name must match
[package]name, and can only use lowercase letters, numbers and-. -
[source]must have asha256. Agit cloneincommandshould use a tag or a commit, which is checked in review. - Dependencies can only use
cmdandstore.
nfb store check --base origin/main --build runs the same checks as a pull request.
Versions are the upstream version as it is, such as 1.1.1w or 4.7.2-stable. A fix to the package itself is a new version such as 19.1.0-2.
Versions come from git history. To publish a new one, edit package.nfb.toml and change version. Every commit that adds a version is where that version lives, and the version added last is the latest, even if it is an older release.
A published version cannot be changed, unless the package is dynamic. To hide a broken one, add it to meta.toml:
yanked = ["19.1.0"]A yanked version cannot be installed and is never the latest. Projects already using it keep working, with a warning.
A package that uses {version} can be installed at any version, not only the ones published. NFB replaces {version} everywhere in the manifest with the version that was asked for. A shell's ${version} is left alone.
[package]
name = "cmake"
version = "4.4.5" # used by nfb install cmake, and the only version sha256 covers
[source]
url = "https://github.com/Kitware/CMake/releases/download/v{version}/cmake-{version}-linux-x86_64.tar.gz"
sha256 = "..."
[build]
image = "debian:bookworm-slim"
[[output.artifact]]
from = "cmake-{version}-linux-x86_64/"
to = "."-
nfb install cmake@3.31.12uses the same manifest. If that version doesn't exist or doesn't build, pick another version or another package. - Only the version in
[package]is reviewed and has asha256in the manifest. For any other, the checksum is saved tonfb.lockon the first download, so that download is trusted as it is. - A fix to the manifest doesn't need a new version.
nfb.lockkeeps a project on the manifest it resolved. -
nfb store check --buildonly builds the version in[package]. - Any version can be added to
yanked, even one that was never published.
The history of main must never be rewritten, because metadata.json links to its commits.