Pbuilder

Latest revision as of 04:52, 4 February 2013

Pbuilder is a tool for automatically building and packaging binaries in a clean chroot of an arbitrary Debian / Ubuntu distribution. By abstracting away the particulars of your environment, it helps ensure that your packages install correctly on other machines.

[edit] Prerequisites

The following instructions presume that you already have a source package (.dsc file) and are looking to build and package binaries. If you have not yet created a source package, you will need to do so first. If your project is in Gerrit, you should use git-buildpackage. You may also find it helpful to read the overview of the packaging workflow.

[edit] Setting up your environment

Start by getting your hands on a Labs instance with a misc::package-builder Puppet role (you can add this role if necessary). This will drop a clean install image in /var/cache/pbuilder/distribution.tgz. (Alternately, you can create a clean install image manually using pbuilder create.)

Create a packaging/ directory in your home directory and copy the image there. Next, configure some useful defaults in ~/.pbuilderrc (creating it if it does not exist):

  DEBEMAIL="Your Name <your.email@wikimedia.org>"
  BASETGZ="/home/yourname/packaging/precise.tgz"  # Path must be canonical and absolute
  APTCONFDIR="/etc/apt" # Use host environment's apt config -- see below for caveat
  DEBBUILDOPTS="-sa"    # Include source -- required for inclusion in Wikimedia repo

Note: whenever BASETGZ is not recognized, you can pass the full pass to the tgz using --basetgz:

pbuilder build --basetgz /var/cache/pbuilder/precise.tgz some.dsc

The APTCONFDIR copies your apt configuration to the build environment. This will add the Wikimedia apt repositories, which allows your package to have dependencies on other packages in our repository. However, this only works if your host is running the same distribution as the one you are targeting. If you added the APTCONFDIR line, you should update the image, which will complete the build environment's apt configuration:

 # sudo pbuilder update --override-config

If you are targeting a different distribution or wish to include other repositories, you can declare them in pbuilderrc (see man pbuilderrc), or you can configure your build environment in an interactive session, by running pbuilder login --save-after-login and making the required modifications by hand.

[edit] Build

When you are ready to build a package, use:

# sudo pbuilder build package.dsc

If you would like to use a different base image, you can specify it using the --basetgz command-line argument. (Other defaults are similarly overridable -- see the man page for pbuilder.)

If all goes well, you'll find the resulting package(s) in /var/cache/pbuilder/result.

[edit] Upload to repository

The final step is to upload your package for inclusion in the repository. This is done using Reprepro.

[edit] Tips

[edit] Targeting different archs

Create a new distribution image using another filename:

# pbuilder create --distribution precise --debootstrapopts --arch --debootstrapopts i386 \
            --basetgz ~/packaging/base-i386.tgz

Then, to build a 32 bit package:

# linux32 pbuilder build --basetgz /var/cache/pbuilder/base-i386.tgz --debbuildopts "-sa" package.dsc

The debbuildopts argument forces the inclusion of the package source, a requirement for inclusion in the Wikimedia repository.

[edit] Modifying the base image

As noted earlier, the easiest way to change something in the base image is via an interactive session:

# pbuilder login --save-after-login

This will drop you into an interactive session in the target environment. You can make whatever modifications you need; once you log out, the environment's image will be rebuilt with your modifications.

[edit] External documentation

• Pbuilder Howto (Ubuntu-specific)
• Pbuilder documentation (PDF)
• pbuilder man page
• pbuilderrc man page