pbuilder User's Manual

pbuilder stands for Personal Builder, and it is an automatic Debian Package Building system for personal development workstation environments. pbuilder aims to be an easy-to-setup system for auto-building Debian packages inside a clean-room environment, so that it is possible to verify that a package can be built on most Debian installations. The clean-room environment is achieved through the use of a base chroot image, so that only minimal packages will be installed inside the chroot.

The Debian distribution consists of free software accompanied with source. The source code within Debian's "main" section must build within Debian "main", with only the explicitly specified build-dependencies installed.

The primary aim of pbuilder is different from other auto-building systems in Debian in that its aim is not to try to build as many packages as possible. It does not try to guess what a package needs, and in most cases it tries the worst choice of all if there is a choice to be made.

In this way, pbuilder tries to ensure that packages tested against pbuilder will build properly in most Debian installations, hopefully resulting in a good overall Debian source-buildability.

The goal of making Debian buildable from source is somewhat accomplished, and has seen good progress. In the past age of Debian 3.0, there were many problems when building from source. More recent versions of Debian is much better.

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.

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

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

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.

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.

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 Chapter 3, Using User-mode-linux with pbuilder.

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:

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:

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.

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.

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:

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 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

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.

user-mode-linux isn't completely trivial to set up. It would probably be useful to acquaint yourself with it a bit before attempting to use rootstrap or pbuilder-user-mode-linux. For details, read /usr/share/doc/uml-utilities/README.Debian and the user-mode-linux documentation. (It's in a separate package, user-mode-linux-doc.)

user-mode-linux requires the user to be in the uml-net group in order to configure the network unless you are using slirp.

If you compile your own kernel, you may want to verify that you enable TUN/TAP support, and you might want to consider the SKAS patch.

rootstrap is a wrapper around debootstrap. It creates a Debian disk image for use with UML. To configure rootstrap, there are several requirements.

The following needs to happen:

pbuilder-user-mode-linux emulates most of pbuilder, but there are some differences.

To run pbuilder-user-mode-linux in parallel on a system, there are a few things to bear in mind.

It is possible to use pbuilder-user-mode-linux for other uses than just building Debian packages. pbuilder-user-mode-linux login will let a user use a shell inside the user-mode-linux pbuilder base image, and pbuilder-user-mode-linux execute will allow the user to execute a script inside the image.

You can use the script to install ssh and add a new user, so that it is possible to access inside the user-mode-linux through ssh.

Note that it is not possible to use a script from /tmp due to the way pbuilder-user-mode-linux mounts a tmpfs at /tmp.

The following example script may be useful in starting a sshd inside user-mode-linux.

#!/bin/bash

apt-get install -y ssh xbase-clients xterm
echo "enter root password"
passwd
cp /etc/ssh/sshd_config{,-}
sed 's/X11Forwarding.*/X11Forwarding yes/' /etc/ssh/sshd_config- > /etc/ssh/sshd_config

/etc/init.d/ssh restart
ifconfig
echo "Hit enter to finish"
read

It often happens that pbuilder cannot create the latest chroot. Try upgrading pbuilder and debootstrap. It is currently only possible to create software that handles the past. Future prediction is a feature which may be added later after we have become comfortable with the past.

There are people who occasionally back port debootstrap to stable versions; hunt for them.

When there are errors with the debootstrap phase, the debootstrap script needs to be fixed. pbuilder does not provide a way to work around debootstrap.

Because of the way pbuilder works, there are several directories which cannot be bind-mounted when running pbuilder. The directories include /tmp, /var/cache/pbuilder, and system directories such as /etc and /usr. The recommendation is to use directories under the user's home directory for bind-mounts.

It is possible to invoke a shell session after a build failure. Example hook script are provided as C10shell and C11screen scripts. C10shell script will start bash inside chroot, and C11screen script will start GNU screen inside the chroot.

It is sometimes necessary to modify the chroot environment. login will remove the contents of the chroot after logout. It is possible to invoke a shell using hook scripts. pbuilder update executes 'E' scripts, and a sample for invoking a shell is provided as C10shell.

$ mkdir ~/loginhooks
$ cp C10shell ~/loginhooks/E10shell
$ sudo pbuilder update --hookdir ~/loginhooks/E10shell

It is also possible to add --save-after-exec and/or --save-after-login options to the pbuilder login session to accomplish the goal. It is possible to add the --uml-login-nocow option to pbuilder-user-mode-linux login session as well.

It is possible to set

BUILDRESULTUID=$SUDO_UID

in pbuilderrc to set the proper BUILDRESULTUID when using sudo.

If you are setting $TMPDIR to an unusual value, of other than /tmp, you will find that some errors may occur inside the chroot, such as dpkg-source failing.

There are two options, you may install a hook to create that directory, or set

export TMPDIR=/tmp

in pbuilderrc. Take your pick.

An example script is provided as examples/D10tmp with pbuilder.

When working with multiple chroots, it would be nice to work with scripts that reduce the amount of typing. An example script pbuilder-distribution.sh is provided as an example. Invoking the script as pbuilder-squeeze will invoke pbuilder with a squeeze chroot.

This section^[6] describes briefly a way to setup and use multiple pbuilder setups by creating a pbuilderrc configuration in your home path ($HOME/.pbuilderrc) and using the variable "DIST" when running pbuilder or pdebuild.

First, setup $HOME/.pbuilderrc to look like:

if [ -n "${DIST}" ]; then
        BASETGZ="`dirname $BASETGZ`/$DIST-base.tgz"
        DISTRIBUTION="$DIST"
        BUILDRESULT="/var/cache/pbuilder/$DIST/result/"
        APTCACHE="/var/cache/pbuilder/$DIST/aptcache/"
fi

Then, whenever you wish to use pbuilder for a particular distro, assign a value to "DIST" that is one of the distros available for Debian or any Debian based distro you happen to be running (i.e. whatever is found under /usr/lib/debootstrap/scripts).

Here's some examples on running pbuilder or pdebuild:

DIST=gutsy sudo pbuilder create

DIST=sid sudo pbuilder create --mirror http://http.us.debian.org/debian

DIST=gutsy sudo pbuilder create \
        --othermirror "deb http://archive.ubuntu.com/ubuntu gutsy universe \
        multiverse"

DIST=gutsy sudo pbuilder update

DIST=sid sudo pbuilder update --override-config --mirror \
http://http.us.debian.org/debian \
--othermirror "deb http://http.us.debian.org/debian sid contrib non-free"

DIST=gutsy pdebuild

If you have some very specialized requirements on your apt setup inside pbuilder, it is possible to specify that through the --othermirror option. Try something like: --othermirror "deb http://local/mirror stable main|deb-src http://local/source/repository ./"

To use the local file system instead of HTTP, it is necessary to do bind-mounting. --bindmounts is a command-line option useful for such cases.

It might be convenient to use your built packages from inside the chroot. It is possible to automate the task with the following configuration. First, set up pbuilderrc to bindmount your build results directory.

BINDMOUNTS="/var/cache/pbuilder/result"

Then, add the following hook

# cat /var/cache/pbuilder/hooks/D70results
#!/bin/sh
cd /var/cache/pbuilder/result/
/usr/bin/dpkg-scanpackages . /dev/null > /var/cache/pbuilder/result/Packages
/usr/bin/apt-get update

This way, you can use deb file:/var/cache/pbuilder/result

To add new apt-key inside chroot:

sudo pbuilder --login --save-after-login
# apt-key add - <<EOF
...public key goes here...
EOF
# logout