Using pbuilder

There are several simple commands for operation. pbuilder create, pbuilder update, and pbuilder build commands are the typical commands used. Let us look at the commands one by one.

Creating a base chroot image tar-ball

pbuilder create will create a base chroot image tar-ball (base.tgz). All other commands will operate on the resulting base.tgz If the Debian release to be created within chroot is not going to be “sid” (which is the default), the distribution code-name needs to be specified with the --distribution command-line option.

debootstrap [1] is used to create the bare minimum Debian installation, and then build-essential packages are installed on top of the minimum installation using apt-get inside the chroot.

For fuller documentation of command-line options, see the pbuilder(8) manual page. Some configuration will be required for /etc/pbuilderrc for the mirror site [2] to use, and proxy configuration may be required to allow access through HTTP. See the pbuilderrc(5) manual page for details.

Updating the base.tgz

pbuilder update will update the base.tgz. It will extract the chroot, invoke apt-get update and apt-get dist-upgrade inside the chroot, and then recreate the base.tgz (the base tar-ball).

It is possible to switch the distribution which the base.tgz is targeted at at this point. Specify --distribution sid --override-config to change the distribution to sid [3].

For fuller documentation of command-line options, see the pbuilder(8) manual page

Building a package using the base.tgz

To build a package inside the chroot, invoke pbuilder build whatever.dsc. pbuilder will extract the base.tgz to a temporary working directory, enter the directory with chroot, satisfy the build-dependencies inside chroot, and build the package. The built packages will be moved to a directory specified with the --buildresult command-line option.

The --basetgz option can be used to specify which base.tgz to use.

pbuilder will extract a fresh base chroot image from base.tgz. (base.tgz is created with pbuilder create, and updated with pbuilder update). The chroot is populated with build-dependencies by parsing debian/control and invoking apt-get.

For fuller documentation of command-line options, see the pbuilder(8) manual page

Facilitating Debian Developers’ typing, pdebuild

pdebuild is a little wrapper script that does the most frequent of all tasks. A Debian Developer may try to do debuild, and build a package, inside a Debian source directory. pdebuild will allow similar control, and allow package to be built inside the chroot, to check that the current source tree will build happily inside the chroot.

pdebuild calls dpkg-source to build the source packages, and then invokes pbuilder on the resulting source package. However, unlike debuild, the resulting deb files will be found in the --buildresult directory.

See the pdebuild(1) manual page for more details.

There is a slightly different mode of operation available in pdebuild since version 0.97. pdebuild usually runs debian/rules clean outside of the chroot; however, it is possible to change the behavior to run it inside the chroot with the --use-pdebuild-internal. It will try to bind mount the working directory inside chroot, and run dpkg-buildpackage inside. It has the following characteristics, and is not yet the default mode of operation.

  • Satisfies build-dependency inside the chroot before creating source package. (which is a good point that default pdebuild could not do).
  • The working directory is modified from inside the chroot.
  • Building with pdebuild does not guarantee that it works with pbuilder.
  • If making the source package fails, the session using the chroot is wasted (chroot creation takes a bit of time, which should be improved with cowdancer).
  • Does not work in the same manner as it used to; for example, --buildresult does not have any effect.
  • The build inside chroot is ran with the current user outside chroot.

Configuration Files

It is possible to specify all settings by command-line options. However, for typing convenience, it is possible to use a configuration file.

/etc/pbuilderrc and $HOME/.pbuilderrc are read in when pbuilder is invoked. The possible options are documented in the pbuilderrc(5) manual page.

It is useful to use --configfile option to load up a preset configuration file when switching between configuration files for different distributions.

Please note $HOME/.pbuilderrc supersede system settings. Caveats is that if you have some configuration, you may need to tweak the configuration to work with new versions of pbuilder when upgrading.

Building packages as non-root inside the chroot

pbuilder requires full root privilege when it is satisfying the build-dependencies, but most packages do not need root privilege to build, or even refused to build when they are built as root. pbuilder can create a user which is only used inside pbuilder and use that user id when building, and use the fakeroot command when root privilege is required.

BUILDUSERID configuration option should be set to a value for a user id that does not already exist on the system, so that it is more difficult for packages that are being built with pbuilder to affect the environment outside the chroot. When BUILDUSERNAME configuration option is also set, pbuilder will use the specified user name and fakeroot for building packages, instead of running as root inside chroot.

Even when using the fakerooting method, pbuilder will run with root privilege when it is required. For example, when installing packages to the chroot, pbuilder will run under root privilege.

To be able to invoke pbuilder without being root, you need to use user-mode-linux, as explained in Using User-mode-linux with pbuilder.

Using pbuilder for back-porting

pbuilder can be used for back-porting software from the latest Debian distribution to the older stable distribution, by using a chroot that contains an image of the older distribution, and building packages inside the chroot. There are several points to consider, and due to the following reasons, automatic back-porting is usually not possible, and manual interaction is required:

  • The package from the unstable distribution may depend on packages or versions of packages which are only available in unstable. Thus, it may not be possible to satisfy Build-Depends: on stable (without additional backporting work).
  • The stable distribution may have bugs that have been fixed in unstable which need to be worked around.
  • The package in the unstable distribution may have problems building even on unstable.

Mass-building packages

pbuilder can be automated, because its operations are non-interactive. It is possible to run pbuilder through multiple packages non-interactively. Several such scripts are known to exist. Junichi Uekawa has been running such a script since 2001, and has been filing bugs on packages that fail the test of pbuilder. There were several problems with auto-building:

  • Build-Dependencies need to install non-interactively, but some packages are so broken that they cannot install without interaction (like postgresql).
  • When a library package breaks, or gcc/gcj/g++ breaks, or even bison, a large number of build failures are reported. (gcj-3.0 which had no “javac”, bison which got more strict, etc.)
  • Some people were quite hostile against build failure reports.

Most of the initial bugs have been resolved in the pbuilder sweep done around 2002, but these transitional problems which affect a large portion of Debian Archive do arise from time to time. Regression tests have their values.

A script that was used by Junichi Uekawa in the initial run is now included in the pbuilder distribution, as pbuildd.sh. It is available in /usr/share/doc/pbuilder/examples/pbuildd/ and its configuration is in /etc/pbuilder/pbuildd-config.sh. It should be easy enough to set up for people who are used to pbuilder. It has been running for quite a while, and it should be possible to set the application up on your system also. This version of the code is not the most tested, but should function as a starter.

To set up pbuildd, there are some points to be aware of.

  • A file ./avoidlist needs to be available with the list of packages to avoid building.
  • It will try building anything, even packages which are not aimed for your architecture.
  • Because you are running random build scripts, it is better to use the fakeroot option of pbuilder, to avoid running the build under root privilege.
  • Because not all builds are guaranteed to finish in a finite time, setting a timeout is probably necessary, or pbuildd may stall with a bad build.
  • Some packages require a lot of disk space, around 2GB seems to be sufficient for the largest packages for the time being. If you find otherwise, please inform the maintainer of this documentation.

Auto-backporting scripts

There are some people who use pbuilder to automatically back-port a subset of packages to the stable distribution.

I would like some information on how people are doing it, I would appreciate any feedback or information on how you are doing, or any examples.

Using pbuilder for automated testing of packages

pbuilder can be used for automated testing of packages. It has the feature of allowing hooks to be placed, and these hooks can try to install packages inside the chroot, or run them, or whatever else that can be done. Some known tests and ideas:

  • Automatic install-remove-install-purge-upgrade-remove-upgrade-purge test-suite (distributed as an example, B91dpkg-i), or just check that everything installs somewhat (execute_installtest.sh).
  • Automatically running lintian (distributed as an example in /usr/share/doc/pbuilder/examples/B90lintian).
  • Automatic debian-test of the package? The debian-test package has been removed from Debian. A pbuilder implementation can be found as debian/pbuilder-test directory, implemented through B92test-pkg script.

To use B92test-pkg script, first, add it to your hook directory. [4]. The test files are shell scripts placed in debian/pbuilder-test/NN_name (where NN is a number) following run-parts standard [5] for file names. After a successful build, packages are first tested for installation and removal, and then each test is ran inside the chroot. The current directory is the top directory of the source-code. This means you can expect to be able to use ./debian/ directory from inside your scripts.

Example scripts for use with pbuilder-test can be found in /usr/share/doc/pbuilder/examples/pbuilder-test.

Using pbuilder for testing builds with alternate compilers

Most packages are compiled with gcc or g++ and using the default compiler version, which was gcc 2.95 for Debian GNU/Linux 3.0 (i386). However, Debian 3.0 was distributed with other compilers, under package names such as gcc-3.2 for gcc compiler version 3.2. It was therefore possible to try compiling packages against different compiler versions. pentium-builder provides an infrastructure for using a different compiler for building packages than the default gcc, by providing a wrapper script called gcc which calls the real gcc. To use pentium-builder in pbuilder, it is possible to set up the following in the configuration:

EXTRAPACKAGES="pentium-builder gcc-3.2 g++-3.2"
export DEBIAN_BUILDARCH=athlon
export DEBIAN_BUILDGCCVER=3.2

It will instruct pbuilder to install the pentium-builder package and also the GCC 3.2 compiler packages inside the chroot, and set the environment variables required for pentium-builder to function.

[1]debootstrap or cdebootstrap can be chosen
[2]The mirror site should preferably be a local mirror or a cache server, so as not to overload the public mirrors with a lot of access. Use of tools such as apt-proxy would be advisable.
[3]Only upgrading is supported. Debian does not generally support downgrading (yet?).
[4]It is possible to specify --hookdir /usr/share/doc/pbuilder/examples command-line option to include all example hooks as well.
[5]See run-parts(8). For example, no ‘.’ in file names!