Ubuntu Wiki

Introduction

This document describes the steps to setup a chroot jail for building Ubuntu packages using pbuilder. It is recommended for any maintainer of Ubuntu or Debian packages, or anyone interested in building packages using Ubuntu.

You can build packages without pbuilder but you must already have all the build dependencies of the package that you are building installed on your running system.

If you use LVM and want to take advantage of using LVM snapshots to speed up the chroot creation/destruction, please see ["SbuildLVMHowto"] for an alternate approach.

The following assume you want to install edgy. If you need a dapper or feisty chroot, then exchange edgy with the appropriate distribution.

The First Steps

First install the required packages.

sudo apt-get install pbuilder debootstrap devscripts

NOTE: devscripts is not necessary to install along with pbuilder, however if you are serious about using pbuilder and creating and maintaining packages for Ubuntu or Debian, you will want to install devscripts.

Create a chroot base tarball that will contain your chroot cleanroom to build packages with.

sudo pbuilder create 

Rebuilding a package

If everything went well, you should now have a tarball called base.tgz in your system under /var/cache/pbuilder.

To check if you can download source packages, you will need an uncommented deb-src line in /etc/apt/sources.list. It should look like:

    deb-src http://archive.ubuntu.com/ubuntu <ubuntu_version> main restricted universe multiverse

Replace <ubuntu_version> with the version of ubuntu you are using (i.e. feisty, edgy, or dapper). If the line above is there but not uncommented, uncomment it. Make sure your package index files are synchronized so that apt-get knows where to find the sources.

After you ensured the deb-src line is correct and uncommented, run:

    sudo apt-get update

We will build bc, a simple calculator, from source, let's download the debian source package from ubuntu repository:

    apt-get source bc

Now build the package using your chroot cleanroom you created with the command:

    sudo pbuilder build *.dsc

Once the packages are successfully built, the binary and source packages will be stored in /var/cache/pbuilder/result/

Downloading Source Packages Using dget

There will be times when a package you want or need to build is not in the repositories of the current version of Ubuntu you are running. Rather than entering deb-src lines in your sources.list configuration for other versions of Ubuntu you are not running, you can use dget instead to download a package. dget is included in the devscripts package, hence why you should have installed it.

To use dget, first locate the .dsc file of the package you are going to build. Good places to look are http://packages.ubuntu.com/ or http://packages.debian.org/ . Once you located the .dsc file. Copy the link address to it and then in a command prompt run:

    dget <link_address_to_foo.dsc>

NOTE: dget is not included in the devscripts package for Ubuntu dapper.

Signing Source Files

If you intend to upload your packages to ["REVU"], [http://mentors.debian.net/], or any other location, it is highly recommended you sign your source files (.dsc and .changes files). Both ["REVU"] and [http://mentors.debian.net/] enforce signed sources. The easiest way to do this after using pbuilder is by using debsign. Assuming your packages and source files were placed in /var/cache/pbuilder/result/, run;

sudo debsign /var/cache/pbuilder/result/*.changes

debsign is also a part of the package devscripts.

Updating a chroot

It is recommended you update your chroot daily before each build, to do this task use the command below:

    sudo pbuilder update

Speeding up build-dependency calculation

If you use feisty you can use a new build-dependency resolver based on gdebi that should be significantly faster. Change /etc/pbuilder/pbuilderrc to add this line:

    PBUILDERSATISFYDEPENDSCMD="/usr/lib/pbuilder/pbuilder-satisfydepends-gdebi"

Universe support

If you want to rebuild a package from universe or build a new one that needs a package out of main you will need to edit /etc/pbuilderrc again, uncommenting:

    COMPONENTS="main restricted universe multiverse"

After adding the new sources you need to update the chroot, so that it picks up the new apt lines:

    sudo pbuilder update --override-config

Building an i386 pbuilder on AMD64

One of the things a pbuilder is useful for is building i386 packages on an AMD64 machine. You can create an i386 chroot with the command:

    sudo pbuilder create --debootstrapopts --arch --debootstrapopts i386

Multiple pbuilders

When you work with packages, you often want to have multple pbuilders on your machine, if for example you want to backport to Dapper while developing on the development version of Ubuntu (currently Gutsy). Or maybe you want to [https://wiki.ubuntu.com/ContributingToDebian build your packages for Debian] and have them merged back to Ubuntu. The next sections will provide some information to get you started with using multiple pbuilders using Gutsy as an example.

Update debootstrap

It is recommended to use an updated version of debootstrap from the backports repository of whatever version of Ubuntu you are using. You can either activate the backports repository in your sources.list configuration or download the source package using dget, build the packages, and install them.

Setup a pbuilder script

You can adapt the file in /usr/share/doc/pbuilder/examples/pbuilder-distribution.sh. The script needs to be modified so there's no interference with the base pbuilder setup or any other pbuilder setup you will use. The script should look like the following:

# script from Jamin W. Collins  BTS: #255165
# name this script 'pbuilder-gutsy', 'pbuilder-sid', 'pbuilder-dapper' etc.


OPERATION=$1
DISTRIBUTION=`basename $0 | cut -f2 -d '-'`
PROCEED=false
BASE_DIR="/var/cache/pbuilder"
case $OPERATION in
   create|update|build|clean|login|execute )
      PROCEED=true
      ;;
esac
if [ "$PROCEED" = true ]
then
   shift
   sudo /usr/sbin/pbuilder $OPERATION \
      --basetgz $BASE_DIR/$DISTRIBUTION-base.tgz \
      --distribution $DISTRIBUTION \
      --configfile $BASE_DIR/$DISTRIBUTION/pbuilderrc \
      --aptconfdir $BASE_DIR/$DISTRIBUTION/apt.config \
      --buildresult $BASE_DIR/$DISTRIBUTION/result "$@"

else
   echo "Invalid command..."
   echo "Valid commands are:"
   echo "   create"
   echo "   update"
   echo "   build"
   echo "   clean"
   echo "   login"
   echo "   execute"
   exit 1
fi

Save this script in /usr/local/bin and name it according to the distribution you want, e.g. pbuilder-gutsy. Make it executable, type in:

sudo chmod +x /usr/local/bin/pbuilder-gutsy

Next, prepare the staging area. Do this for every distribution you want to build packages for. Again, the examples assume that the distribution you want is gutsy, change the name accordingly for other distributions.

sudo mkdir /var/cache/pbuilder/gutsy
sudo cp /etc/pbuilderrc /var/cache/pbuilder/gutsy/pbuilderrc

Then edit /var/cache/pbuilder/gutsy/pbuilderrc and make sure that the following lines refer to the correct distribution:

DISTRIBUTION=gutsy
BASETGZ=/var/cache/pbuilder/gutsy-base.tgz
BUILDPLACE=/var/cache/pbuilder/gutsy/build/
MIRRORSITE=http://archive.ubuntu.com/ubuntu
BUILDRESULT=/var/cache/pbuilder/gutsy/result/
APTCACHE="/var/cache/pbuilder/gutsy/aptcache/"

For MIRRORSITE, it's best to use a mirror (such as http://us.archive.ubuntu.com/ubuntu for the US) rather than the main archive site. Also, ensure you have the correct mirror site for the distribution your building packages for.

Setup apt.config

Copy the apt configuration files from your system to /var/cache/pbuilder/gutsy/apt.config

sudo cp -R /etc/apt /var/cache/pbuilder/gutsy/apt.config

NOTE: If you are going to use pbuilder to build packages for Debian, it is recommended you configure the apt keys for Debian under your system's apt configuration first before copying the contents of your system's apt directory to /var/cache/pbuilder/<Debian-version>/apt.config.

Next, edit /var/cache/pbuilder/gutsy/apt.config/sources.list according to the distro you'll be building packages for. For Gutsy, it should be no more than one line.

    deb http://us.archive.ubuntu.com/ubuntu/ gutsy main restricted universe multiverse

Create the chroot cleanroom

Finally run sudo pbuilder-gutsy create to create the pbuilder chroot cleanroom (gutsy-base.tgz).

Follow the same steps to create pbuilder chroots for other distributions (e.g. pbuilder-edgy, pbuilder-dapper, pbuilder-sid, etc.).

Troubleshooting "pbuilder create"

There will be sometimes where running sudo pbuilder create will fail to create a base tarball. This normally occurs only when creating base tarballs for development versions of Ubuntu or Debian such as Ubuntu Gutsy or Debian Sid. These are development versions and it is best to wait it out and try at a later date to create a base tarball. It can be days however until creating a base tarball will be successful for these development versions. In the meantime you could create a base tarball for an older version of Ubuntu or Debian and update the tarball to the development version instead.

For example, you can create a pbuilder setup for Debian Etch as described in the previous section. The only thing different you will do is editing the sources.list file to use the Sid repositories instead of the ones for Etch.

deb http://http.us.debian.org/debian sid main

Run sudo pbuilder-etch create. What will happen is that the base packages for Etch will be downloaded, installed, and configured first. Then apt-get update will be performed using the sources.list for the etch pbuilder setup. When the update is run, all packages in need of upgrading will be upgraded and thus, the base packages for Sid will be installed. After pbuilder is done, a base tarball will have been created but named for Etch (etch-base.tgz). All the base packages will be copied into the aptcache directory in /var/cache/pbuilder/etch. From here you can copy the aptcache directory over to the sid directory and make a copy of etch-base.tgz and call it sid-base.tgz.

sudo cp /var/cache/pbuilder/etch/aptcache /var/cache/pbuilder/sid/aptcache
sudo cp /var/cache/pbuilder/etch-base.tgz /var/cache/pbuilder/sid-base.tgz

It is better of course to create a base tarball directly using the appropriate script and pbuilder setup. Check often to see if a base tarball can be created directly.

pdebuild

pdebuild is the pbuilder way of doing debuild. It comes along with the pbuilder package. pdebuild is essentially run the same way as debuild. Go into the source tree containing the debian directory and type:

pdebuild

See also the [http://penguin-soft.com/penguin/man/1/pdebuild.html pdebuild man page].

Using pdebuild for multiple pbuilder setups

A pdebuild script can be setup in the same way as a pbuilder script to build packages for multiple versions of Ubuntu or Debian. The following script will allow for using options the same way as they are used in pdebuild.

# script from Andres Mejia
# name this script 'pbuilder-gutsy', 'pbuilder-sid', 'pbuilder-dapper' etc.

DISTRIBUTION=`basename $0 | cut -f2 -d '-'`
BASE_DIR="/var/cache/pbuilder"
ALL_OPTIONS="$@"
PDEBUILD_OPTIONS="`echo "$ALL_OPTIONS" | sed 's/-- .*$//'`"
PBUILDER_OPTIONS="`echo "$ALL_OPTIONS" | sed '/^.*[--][\ ].*$/ !{d}' | sed 's/^.*-- //'`"

pdebuild --buildresult $BASE_DIR/$DISTRIBUTION/result \
--configfile $BASE_DIR/$DISTRIBUTION/pbuilderrc $PDEBUILD_OPTIONS \
-- \
--basetgz $BASE_DIR/$DISTRIBUTION-base.tgz \
--distribution $DISTRIBUTION \
--aptconfdir $BASE_DIR/$DISTRIBUTION/apt.config $PBUILDER_OPTIONS

Rename this script pdebuild-<distro_version> where <distro_version> is something like gutsy or feisty. Save this script under /usr/local/bin and make it executable. Then whenever you want to build a package in a particular version of Ubuntu or Debian, run this script the same way pdebuild would be run. That is:

pdebuild-<distro_version> <pdebuild_options> <etc.> -- <pbuilder_options> <etc.>

Installing Pbuilder on Warty, Hoary or Breezy

Install pbuilder package and debootstrap.

Edit /etc/pbuilder/pbuilderrc changing the following directives:

    MIRRORSITE=http://archive.ubuntu.com/ubuntu
    DISTRIBUTION=edgy

Since pbuilder will complain about unauthenticated packages, you have to allow unauthenticated packages. You can make it like so:

Edit your /etc/pbuilder/pbuilderrc:

    APTCONFDIR="/etc/pbuilder/apt.config/"

Now you'll copy needed files of /etc/apt to it and

    sudo -s
    mkdir /etc/pbuilder/apt.config/
    cp -ar /etc/apt/* /etc/pbuilder/apt.config/
    echo "APT::Get::AllowUnauthenticated 1;" >> /etc/pbuilder/apt.config/apt.conf.d/allow-unauthenticated
    exit

NOTE: Make sure to remove 99update-notifier from /etc/pbuilder/apt.config/apt.conf.d/ if you have copied it in the last step. It can potentially break future updates to your pbuilder chroot, as update-notifier won't normally be installed.

Save the file and run the command below to build your Edgy chroot:

    sudo pbuilder create --distribution edgy

Running a Shell When Build Fails (Intro to Hook Scripts)

This is done using a hook script. First we need to create a directory to home your pbuilder hooks. This can be anywhere but we'll use a directory called .pbuilder-hooks in your home directory for this example:

    mkdir ~/.pbuilder-hooks

Now we need to tell pbuilder to use this directory as its hooks directory. Edit ~/.pbuilderrc and add the following line, replacing <username> with your username:

    HOOKDIR=/home/<username>/.pbuilder-hooks

Then we need to add a hook script to be called by pbuilder when the build fails. The script needs to be placed in the HOOKDIR and made executable. The name of the hook script is also important. See the pbuilder man page for details. As you can see, for this example, we need to name the script C<digit><digit><whatever-else-you-want> so let's call it C10shell. Edit the new file ~/.pbuilder-hooks/C10shell and add the following:

# invoke shell if build fails.

/bin/bash < /dev/tty > /dev/tty

This script must be made world executable for pbuilder to execute it, so now we run:

    chmod a+x ~/.pbuilder-hooks/C10shell

And you're all set.

See also

pbuilder User's Manual: http://www.netfort.gr.jp/~dancer/software/pbuilder-doc/pbuilder-doc.html

["CategoryMOTU"]