void-packages: the XBPS source package collection for Void Linux

What void-packages solves for Void Linux package maintainers

The Void Linux distribution manages software through XBPS, a package manager that works with binary package files. void-packages provides the source side of that system: every package in the official Void repositories was compiled from a template stored in this repository. The xbps-src script reads those templates, fetches upstream source archives, compiles them inside a controlled chroot environment, and produces binary packages that xbps-install can consume directly.

The goal is reproducibility and isolation. xbps-src refuses to run as the root user and refuses to build directly on the host system. Every build happens inside a directory called the masterdir, which acts as a minimal Void Linux chroot. That design means a failed or badly written build cannot corrupt the host system's libraries or binaries. Contributors who write new package templates work within the same mechanism that produces the official binary packages.

How xbps-src uses the masterdir and fake destdir

The build process works in two stages. First, xbps-src sets up a masterdir containing a bootstrap set of packages that supply the compilers, linkers, and utilities the build system needs. Second, when a package is requested, xbps-src installs build dependencies into the masterdir, compiles the source, and installs the results into a separate directory called the fake destdir rather than directly into the masterdir.

The fake destdir acts as a staging area. xbps-src collects all installed files from the destdir and produces an XBPS binary package file. The finished binary appears in hostdir/binpkgs. Packages under non-free or restricted licenses appear in subdirectories such as hostdir/binpkgs/nonfree. The masterdir is never polluted by the files the package installs at runtime, making it possible to build a sequence of packages without interference between them.

Cloning void-packages and building a first package

Clone the repository and enter it:

git clone https://github.com/void-linux/void-packages.git
cd void-packages

The first build triggers an automatic binary bootstrap, which downloads prebuilt bootstrap packages into the masterdir from remote XBPS repositories. To run it manually:

./xbps-src binary-bootstrap

To build a package by name, pass the pkg target:

./xbps-src pkg <package_name>

After the build, install the resulting binary from the local repository:

xbps-install --repository hostdir/binpkgs <package_name>

Alternatively, the xi utility from the xtools package installs from the local repository automatically without specifying the path:

xi <package_name>

Packages marked restricted are excluded from builds by default. To permit them, append a line to etc/conf:

echo XBPS_ALLOW_RESTRICTED=yes >> etc/conf

Configuration overrides live in etc/conf. The full list of available settings is documented in etc/defaults.conf, which xbps-src reads first. If etc/conf does not exist, xbps-src falls back to $XDG_CONFIG_HOME/xbps-src.conf or ~/.xbps-src.conf.

Chroot methods: kernel requirements and trade-offs

xbps-src supports four chroot mechanisms. The default, xbps-uunshare, relies on Linux user namespaces. It requires CONFIG_NAMESPACES, CONFIG_IPC_NS, CONFIG_UTS_NS, and CONFIG_USER_NS to be enabled in the kernel. If any of those options are absent, the command fails with EINVAL.

The second method is xbps-uchroot, which uses namespaces with a setgid binary. It requires CONFIG_NAMESPACES, CONFIG_IPC_NS, CONFIG_PID_NS, and CONFIG_UTS_NS but not CONFIG_USER_NS. Using it requires adding your user to a group and setting ownership and permissions on the xbps-uchroot binary. On Void Linux itself, members of the xbuilder group get the required access without manual setup. To enable xbps-uchroot:

cd void-packages
echo XBPS_CHROOT_CMD=uchroot >> etc/conf

The third method is bwrap (bubblewrap), a sandboxing tool for unprivileged users. The fourth is ethereal, which the README describes as destroying the host system it runs on. Ethereal exists only for single-use containers such as Docker in CI environments; using it outside a throwaway container would damage the host.

Cross-compilation, musl builds, and 32-bit packages

void-packages supports building packages for architectures different from the host. The Manual.md documents the cross-compilation workflow as a distinct scenario with its own configuration. The README also lists building 32-bit packages on an x86_64 host as a supported use case.

Void Linux ships two libc variants: glibc and musl. void-packages can build packages targeting musl natively. Because musl and glibc are not binary-compatible, packages that rely on glibc-specific extensions require separate handling in the template. Contributors targeting both variants must address compatibility in the template itself rather than in build flags alone.

The repository also documents procedures for building the entire Void base system from scratch, and for keeping a masterdir up to date as the bootstrap packages themselves evolve.

Where xbps-src falls short

The rootless chroot requirement is the primary operational constraint. Any environment that disables user namespaces at the kernel level, or enforces them only for privileged processes, will fail to initialize a masterdir. Unprivileged Docker containers and certain virtualization environments commonly hit this limit.

The ethereal backend sidesteps namespace support but destroys the host file system in the process. It has no safe use outside a disposable container.

A full source bootstrap, which builds all bootstrap packages from source using the host system's toolchain, is described in the README as non-reproducible. The host compiler and installed utilities influence the result. The README explicitly recommends binary-bootstrap for all normal use and treats a source bootstrap only as a stage 0 for bringing up entirely new Void system ports.

The requirement for xbps 0.56 or newer also means xbps-src cannot be set up on distributions that ship significantly older XBPS builds without first updating that dependency separately.

How void-packages compares to Arch Linux's makepkg

Arch Linux uses makepkg with PKGBUILD scripts stored in the Arch Build System and the Arch User Repository. Both void-packages and makepkg compile software from source and produce binary packages. The key difference is chroot handling. makepkg can build directly on the host system without any chroot by default, which makes it usable on almost any Linux system with the required build tools. xbps-src requires a chroot and refuses to proceed without one, which gives stronger build isolation at the cost of requiring namespace support.

For anyone targeting Void Linux specifically, void-packages is the only path to producing packages that can be submitted to the official repository. There is no equivalent to the AUR's user-submitted PKGBUILDs that install without the official build infrastructure.

Editorial conclusion

Engineers running Void Linux who need to package software not yet in the official repositories, or who want to contribute new templates, should clone void-packages and work through xbps-src. The rootless chroot requirement is a hard constraint: anyone on a system without namespace support, such as older kernels or certain containers, will encounter EINVAL before a single build completes. Verify kernel options CONFIG_NAMESPACES, CONFIG_IPC_NS, CONFIG_UTS_NS, and CONFIG_USER_NS before starting.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. void-linux/void-packages on GitHub