pbuilder

pbuilder [options] command [arguments]

Common commands:
pbuilder build [options] source.dsc
pbuilder update [options]
pbuilder create [options]
pbuilder login [options]

-C, --configfile <file>
    Specifies an alternative configuration file to use instead of the default /etc/pbuilderrc or ~/.pbuilderrc.

-D, --distribution <dist>
    Sets the target Debian distribution for the chroot (e.g., stable, unstable, bookworm).

-B, --buildplace <dir>
    Defines the base directory where the chroot environment will be created and managed.

-U, --update
    Ensures the base chroot image is updated with the latest packages before a build or operation.

-u, --override-config <var>=<value>
    Overrides specific configuration variables defined in the pbuilderrc file.

-p, --pbuilderootdir <dir>
    Specifies the root directory for all pbuilder-related files, including the chroot and cache.

-r, --buildresult <dir>
    Designates the directory where the built Debian packages (.deb, .changes, etc.) will be placed.

-w, --what-to-do-when-error <action>
    Determines the action to take if a build error occurs (e.g., login to the chroot, halt, unmount).

--bindmounts <list>
    A comma-separated list of directories from the host system to bind mount into the chroot environment.

--hookdir <dir>
    Specifies a directory containing custom hook scripts to be executed at various build stages.

-v, --version
    Displays the program's version information.

-h, --help
    Shows a help message and exits.

pbuilder is a crucial tool for Debian and derivative distributions, designed to build Debian packages (.deb) within a clean, isolated chroot environment. Its primary objective is to ensure that packages are built solely against their declared build dependencies, thereby preventing accidental reliance on locally installed packages. This isolation is vital for identifying missing build dependencies early, guaranteeing package reproducibility, and enhancing portability across diverse systems.

The process involves creating a base chroot image, updating it with the latest packages, and then utilizing this pristine image for building source packages. After a build concludes, the environment is either discarded or reverted to its original state, ensuring a fresh slate for every subsequent build. This methodology is indispensable for package maintainers and developers, as it effectively counters the "builds-on-my-machine" syndrome and significantly contributes to the robustness and correctness of the Debian archive. pbuilder supports multiple architectures and offers extensive configuration options for tailoring build environments.

Using pbuilder requires significant disk space, especially for multiple chroot environments and built packages. Initial chroot creation or extensive dependency updates can be time-consuming. Advanced configurations, such as custom hooks or managing various distributions and architectures, can introduce complexity. Additionally, pbuilder operations typically require root privileges to manage the chroot environment effectively.

pbuilder heavily relies on configuration files, primarily /etc/pbuilderrc and ~/.pbuilderrc. These files allow users to define default behaviors for their build environments, including the target distribution, architecture, package repositories, and the location of chroots. This robust configuration system enables highly customized and repeatable build processes without the need for extensive command-line options for every operation.

A powerful feature of pbuilder is its support for 'hooks.' These are custom scripts that can be executed at various predefined stages of the build process, such as before chroot creation, after updating the base image, prior to the actual package build, or after the build completes. This allows for advanced automation, including installing specific build tools, setting up temporary package repositories, performing custom checks, or exporting detailed build logs, greatly extending pbuilder's flexibility.

pbuilder was developed by Junichi Uekawa, with its initial release dating back to approximately 2002. It rapidly became an indispensable utility for Debian maintainers and developers by addressing the critical need for clean and reproducible package build environments. Prior to pbuilder, developers often relied on manual chroot setups, which were prone to inconsistencies. pbuilder formalized and automated this process, mitigating the "works on my machine" problem. Its design and principles have profoundly influenced subsequent build tools like cowbuilder (which optimizes performance using copy-on-write techniques) and sbuild. pbuilder continues to be actively maintained and remains a cornerstone of the Debian package building ecosystem, ensuring high-quality and reliable software packages.

debuild(1), dpkg-buildpackage(1), cowbuilder(1), schroot(1), mk-build-deps(1)