Building Debian and Ubuntu packages with pbuilder

May 17, 2015 · 5 min read

debian-how-to

TL;DR

pbuilder is a tool for building Debian and Ubuntu packages. You can use pbuilder to build packages for many different versions of Debian and Ubuntu.

The main advantage of using pbuilder to build Debian and Ubuntu packages instead of debuild is that pbuilder builds Deb packages in a cleanroom environment. pbuilder does this by creating a chroot and performing the Deb package build in the chroot.

This article explains how to setup, configure, and build packages with pbuilder.

Setup

Install pbuilder on Debian and Ubuntu

To install pbuilder, run the following command:

$ sudo apt-get install pbuilder debootstrap devscripts

Prepare your build

Once you’ve installed pbuilder, you must next prepare the Debian source package to be built.

pbuilder builds binary deb packages from source packages. So, before you can do your build, you must either generate a Debain source package yourself or download an existing source package you’d like to build.

To generate your own debian source package, you will need to write your own debian packaging.

If you are rebuilding an existing source package, you must download the debian source package.

Building a Deb package with pbuilder

pbuilder config files

Now that you’ve either downloaded or built the debian source package, you can use pbuilder to generate the binary deb package.

You can specify all options required by pbuilder on the command line. If you like, you can also create a configuration file containing all your configuration options to simplify your pbuilder command line.

/usr/share/pbuilder/pbuilderrc - The default settings for most pbuilder options can be found in this file. Any required options missing from other files will be taken from this file.
/etc/pbuilderrc - The system-wide pbuilder configuration. Configuration values specified in this file will be available to all users on the system who run pbuilder.
${HOME}/.pbuilderrc - Finally, you may specify per-user configuration values by creating a file named .pbuilderrc in your home directory. Settings in this file override configuration settings in the previous two configuration files.

A typical pbuilder configuration will set a few useful environment variables that will be used by pbuilder:

BASETGZ: The location of the base chroot tarball. If you are planning to build packages for multiple distributions of Debian and/or Ubuntu, you should set this option so that the chroots don’t overwrite each other. For example, you might want to set this to something like: BASETGZ=/var/cache/pbuilder/$NAME-base.tgz.
DISTRIBUTION: The distribution of Ubuntu or Debian to use.
ARCHITECTURE: The CPU architecture to use.
MIRRORSITE: The Ubuntu or Debian APT mirror to use. This is useful to set to near-by mirror or even a mirror on your local disk. This can speed up package builds quite a bit.

You can find a comprehensive list of options by checking the pbuilderrc man page:

$ man 5 pbuilderrc

The examples below will pass all necessary configuration options on the command line to make it more clear what exactly is happening.

Initializing and deleting the pbuilder chroot

You can initialize the pbuilder chroot before performing the first build. This will reduce the build time when you do perform the build later.

pbuilder will re-use the base chroot after it has been initialized. This helps to reduce build time.

In order to initialize the chroot for a build on an amd64 Ubuntu Trusty chroot, run the command:

$ sudo pbuilder --create                \
                --distribution trusty   \
                --architecture amd64    \
                --basetgz /var/cache/pbuilder/trusty-amd64-base.tgz

Putting the distribution and architecture in the filename of the base chroot is strongly recommended.

To delete the chroot, simply remove the base chroot tarball:

$ sudo rm /var/cache/pbuilder/trusty-amd64-base.tgz

Performing the build

To perform a build, you’ll need to specify the path to your debian source package control file (.dsc file):

$ sudo pbuilder --build                                               \
                --distribution trusty                                 \
                --architecture amd64                                  \
                --basetgz /var/cache/pbuilder/trusty-amd64-base.tgz   \
                /path/to/package.dsc

The build may take some time if you have not previously initialized an Ubuntu Trusty amd64 chroot before.

Once the build has concluded, you will find the resulting files in $BUILDRESULT. The default value for this is: /var/cache/pbuilder/result/.

You can change this on the command line by passing the --buildresult flag.

Conclusion

Using pbuilder when building Debian and Ubuntu packages allows you to build debs for multiple architectures, ensures that the resulting debs contain no artifacts from previous builds, and provides a simple interface for reproducible builds.

Users who currently build binary debs with just debuild are strongly encouraged to consider how their build process might be modified to support the use of pbuilder.