Glossary

A lot of these words mean something slightly different in other distributions, or nothing at all. This is what they mean here. Each entry links to the page or post that goes into more detail.

There's one naming habit that helps: a registry is written in lowercase (base, common), and the repository built from it is capitalized (Base, Common). One is where recipes live, the other is where packages live.

buildroot

Two related meanings. First: the directory tree that a single build runs in, which becomes / inside the sandbox. It holds the floor plus the packages the recipe lists in [build_deps], and it's thrown away after the build.

Second: the Buildroot-N.R repositories, the self-hosting set of compilers and tools that every other package is built with. Each one is built by the one before it, until two rounds in a row produce byte-identical results. That one is used as the floor for everything else.

clerk key

The signing key that the build host uses for a repository. It signs the repository metadata and every manifest published while it's in use. Each repository has its own clerk key, and it's replaced every few months. A new clerk key only counts when the root key has signed it in. See What gets signed, and by what.

closure

A temporary repository that holds a group of changes that belong together, built against the real repositories as if they had already landed. It's how a change to a hundred interdependent recipes gets built, tested and accepted as one unit, instead of one recipe at a time. See dispatcher, part 2.

composition

A description of an image: which packages and sets go in, and what shape comes out (a disk image, an ISO, a container, a WSL image). The dispatcher rebuilds images from their compositions as soon as something in them changes. See pkg-compose(1) and Compositions, part 9.

designer

The tool that writes and changes recipes. It takes a request ("package this", "bump that"), produces a candidate recipe, builds it as a scratch build, and runs the license, malware, vulnerability and lint checks on it. Coding agents talk to it, but it's designed so that they can only propose. Nothing the designer produces lands in a registry until a human approves it. It also holds the recipe formatter and linter (designer fmt, designer lint). See Designer, part 13.

dispatch

The name of the build system as a whole: the dispatcher daemon, plus the tools that talk to it: dispatch-web for review and approval in a browser, dispatch-tui in a terminal, and dispatch-cli for scripts. On a build host, all of them run as the dispatch user. The Deploying the build system guide sets one up.

dispatcher

The daemon at the center of dispatch. It reads registries, decides what needs to be built, runs the builds in a sandbox, publishes the results into repositories, and rebuilds images. It has no fixed build order. Whenever a recipe's dependencies are all built, it can be built. Its configuration is dispatch.toml(5).

floor

The bottom layer of every build: the compiler, make, the C library and the other basic tools that every recipe can assume are there. It comes from the current buildroot repository. A recipe doesn't list floor packages in [build_deps], except when it needs the headers of a floor library.

in-tree source

A [[source]] in a recipe that's a directory inside the recipe itself, instead of a download. Used for small files like configuration, and for packages that only exist in this project. See How an in-tree source works.

manifest

The signed description of one package: its name, version, dependencies, and the SHA-256 of every file in it. It's stored as a .pkg-meta file, next to a .pkg-data file that holds the actual files. After installation, the manifest is the record of what's installed.

package

What pkg installs. One recipe builds one package, which is split into several subpackages. In practice, "package" often means a single subpackage, like gcc/bin. See Packages, part 7.

probe

The part of the build that recognizes one build system and knows how to run it: autotools, meson, cmake, cargo, make and so on. Every probe checks whether it applies to a source tree, and the best one that applies runs the configure, build and install steps. A recipe almost never needs to say which build system it uses. See [probes].

provenance

The signed record of how a build was made: which sources went in, by SHA-256, which packages were in the buildroot, and which upstream signatures were checked. It lets anyone check a package's history and rebuild it to compare. See pkg-provenance(1).

recipe

A directory with a recipe.toml file, and maybe some patches and other files, that describes how to build one upstream source into a package: where to download it, how to check it, what to patch, and what it needs to build. Most recipes are short, because the build works out most things itself. The recipe.toml reference describes every key, and The recipe format, part 4 explains why it looks the way it does.

registry

A git repository of recipes. It has a recipes/ directory with one recipe per directory, a registry.toml that lists the recipes that count, and a sets/ directory with the sets. The official ones are base and common. A registry is only the input. What comes out is a repository. See The registry, part 5.

release

The number after the version, like the 8 in sudo 1.9.17p2 release 8. It goes up by one when a recipe changes without a new upstream version, and starts at 1 again when the version changes.

repository

Where built, signed packages are published, and where pkg installs them from. A repository is a set of stores where every file is named by its SHA-256, plus TUF metadata that says what's current and is signed. The official ones are Sandcastle-Base and Sandcastle-Common, and a system can use more than one at a time. See pkg-repos.d(5), pkg-repository-layout(7) and Repositories, part 8.

Note that git repositories (the registries) and package repositories are not the same thing. In these docs, "repository" means the package kind, unless it says git.

root key

The key at the top of the trust chain for a repository. It signs the TUF root files that say which clerk key is valid, and nothing else. There's one per repository, and it's kept offline. It only comes out for a key ceremony. See The signs are there and the Security page for the fingerprints.

sandbox

The isolated environment every build runs in. No network, its own filesystem root, its own process and user namespaces, a seccomp filter and Landlock rules. It's there so that a build can't reach anything except its own buildroot, even when the code it builds is hostile.

Sandcastle

The operating system that The Ur Project builds, and the name of its stream. The images on the Download page are Sandcastle.

SBOM

Software Bill of Materials: a list of everything that went into a package or an image, with versions and licenses. Every build produces one in SPDX and in CycloneDX format. See pkg-sbom(1).

scratch build

A build of a single recipe directory, without a registry. The result goes into a throwaway repository of its own and can never be published by accident. The designer uses scratch builds to try out every recipe it writes, and pkg build is a scratch build on your own machine.

set

A named group of packages, like everything a GNOME desktop needs. pkg remembers which sets you installed, so when a set changes in an update, your system follows it. Sets are defined in the sets/ directory of a registry. See pkg-sets(7) and Intent, subpackages, and sets, part 6.

stream

A product line: a group of repositories that are built on top of each other and belong together, like Sandcastle-Base and Sandcastle-Common in the Sandcastle stream. Each repository says which stream it belongs to in its own signed metadata, and pkg warns when a system mixes repositories from two streams.

subpackage

One part of a package. The build splits the files of every package by type: programs in bin, shared libraries in lib, headers in dev, man pages in man, translations in lang/<language>, and so on. A subpackage is written as package/subpackage, like gcc/bin or openssl/lib. pkg installs the ones you need by default and leaves out the rest. See pkg-subpkgs(7) and [classify].

TUF

The Update Framework. A standard for signing repository metadata, so that pkg can tell a real update from a fake one, an old one, or a frozen one, even when it comes from a mirror. See TUF and signing, part 14.

The Ur Project

The project as a whole: the build system, the tools, and everything they produce, including Sandcastle. In names of programs, files and settings it's just ur.

upstream

The original project that a recipe packages, and where its source comes from. "Send it upstream" means getting a fix into that project, so that the recipe doesn't need to carry a patch for it.

upstream watcher

The service that checks upstream projects for new releases. When it finds one, it downloads the new source, updates the version and checksum in the recipe, and hands the change to the designer. A human still reviews and approves it, like any other change.