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.

Installing Pbuilder on edgy

The latest pbuilder package in Edgy (0.155ubuntu3) should work out of the box. You only need to install it and debootstrap. Then run:

sudo pbuilder create 

and then

sudo pbuilder build my-package_1.0.dsc

Note: If you get the error "debootstrap does not exist", install debootstrap.

Rebuilding a package

If you reach this point you now have a Edgy chroot located at /var/cache/pbuilder ready to build a package. We will get a Debian source package from Ubuntu repository to test it.

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

    deb-src http://archive.ubuntu.com/ubuntu edgy main restricted 

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:

    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

You can build the package using your Edgy chroot with the command:

    sudo pbuilder build *.dsc

In the end, the binary and source package will be at /var/cache/pbuilder/result/

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 a part of the package devscripts so you must first install devscripts.

sudo apt-get install devscripts

Updating a chroot

I recommend you update your chroot 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 Edgy. Or maybe you want to [https://wiki.ubuntu.com/ContributingToDebian build your packages for Debian] and have them merged back to Ubuntu.

To do that, you can adapt the file in /usr/share/doc/pbuilder/examples/pbuilder-distribution.sh. That script assumes a common chroot directory for every distribution however, so it's recommended to change the script to the following :

# script from Jamin W. Collins  BTS: #255165
# name this script 'pbuilder-woody', 'pbuilder-sid', 'pbuilder-sarge' 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-feisty. To make it executable, type (use whatever name you have given the script):

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

Next, we'll 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 feisty, change the name for other distributions.

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

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

DISTRIBUTION=feisty
BASETGZ=/var/cache/pbuilder/feisty-base.tgz
BUILDPLACE=/var/cache/pbuilder/feisty/build/
MIRRORSITE=http://archive.ubuntu.com/ubuntu
BUILDRESULT=/var/cache/pbuilder/feisty/result/
APTCACHE="/var/cache/pbuilder/feisty/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.

Now copy the apt configuration files to /var/cache/pbuilder/feisty/apt.config

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

Then edit /var/cache/pbuilder/feisty/apt.config/sources.list and make sure that every occurrence of edgy is changed to feisty.

Finally run pbuilder-feisty create to create the pbuilder chroot (base.tgz) in this location.

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

Note that, to create a Debian pbuilder environment, you will need to make sure you have the Debian keys in the apt-keys used by the chroot. The easiest way to do this is probably to just add them with apt-key to your ubuntu system before copying your apt configuration files to apt.config.

Using pbuilder for the Latest Development Release

If you want to participate in the current release cycle, you will want to have a GutsyGibbon basetgz. This can be done using the method described in the previous section.

One thing to note is that a debootstrap script for gutsy must exist under /usr/lib/debootstrap/scripts/ to create a pbuilder basetgz for gutsy. At this time there is no script installed along with debootstrap to use for gutsy.

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