Chapter 6. Building the package

# Chapter 6. Building the package

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

We should now be ready to build the package.

## 6.1. Complete (re)build

In order to perform a complete (re)build of a package properly, you need to make sure you have installed

- the `build-essential` package,

- packages listed in the `Build-Depends` field (see Section 4.1, “`control`”), and

- packages listed in the `Build-Depends-indep` field (see Section 4.1, “`control`”).

Then you issue the following command in the source directory:

    $ dpkg-buildpackage -us -uc

This will do everything to make full binary and source packages for you. It will:

- clean the source tree (`debian/rules clean`)

- build the source package (`dpkg-source -b`)

- build the program (`debian/rules build`)

- build binary packages (`fakeroot debian/rules binary`)

- make the `.dsc` file

- make the `.changes` file, using dpkg-genchanges

If the build result is satisfactory, sign the `.dsc` and `.changes` files with your private GPG key using the debsign command. You need to enter your secret pass phrase, twice. [62]

For a non-native Debian package, e.g., `gentoo`, you will see the following files in the parent directory (`~/gentoo`) after building packages:

- `gentoo_0.9.12.orig.tar.gz`

  This is the original upstream source code tarball, merely renamed to the above so that it adheres to the Debian standard. Note that this was created initially by the command `dh_make -f ../gentoo-0.9.12.tar.gz`.

- `gentoo_0.9.12-1.dsc`

  This is a summary of the contents of the source code. The file is generated from your `control` file, and is used when unpacking the source with dpkg-source(1).

- `gentoo_0.9.12-1.debian.tar.gz`

  This compressed tarball contains your `debian` directory contents. Each and every addition you made to the original source code is stored as a quilt patch in `debian/patches`.

  If someone else wants to re-create your package from scratch, they can easily do so using the above three files. The extraction procedure is trivial: just copy the three files somewhere else and run `dpkg-source -x gentoo_0.9.12-1.dsc`. [63]

- `gentoo_0.9.12-1_i386.deb`

  This is your completed binary package. You can use dpkg to install and remove this just like any other package.

- `gentoo_0.9.12-1_i386.changes`

  This file describes all the changes made in the current package revision; it is used by the Debian FTP archive maintenance programs to install the binary and source packages. It is partly generated from the `changelog` file and the `.dsc` file.

  As you keep working on the package, its behavior will change and new features will be added. People downloading your package can look at this file and quickly see what has changed. Debian archive maintenance programs will also post the contents of this file to the debian-devel-changes@lists.debian.org mailing list.

The `gentoo_0.9.12-1.dsc` and `gentoo_0.9.12-1_i386.changes` files must be signed using the debsign command with your private GPG key in the `~/.gnupg/` directory, before uploading them to the Debian FTP archive. The GPG signature provides the proof that these files are really yours, using your public GPG key.

The debsign command can be made to sign with your specified secret GPG key ID (good for sponsoring packages) with the following in the `~/.devscripts` file:

    DEBSIGN_KEYID=Your_GPG_keyID

The long strings of numbers in the `.dsc` and `.changes` files are SHA1/SHA256 checksums for the files mentioned. Anyone downloading your files can test them with sha1sum(1) or sha256sum(1) and if the numbers don't match, they'll know the file is corrupt or has been tampered with.

## 6.2. Autobuilder

Debian supports many ports with the autobuilder network running buildd daemons on computers of many different architectures. Although you do not need to do this yourself, you should be aware of what will happen to your packages. Let's look into roughly how they rebuild your packages for multiple architectures. [64]

For `Architecture: any` packages, the autobuilder system performs a rebuild. It ensures the installation of

- the `build-essential` package, and

- packages listed in the `Build-Depends` field (see Section 4.1, “`control`”).

Then it issues the following command in the source directory:

    $ dpkg-buildpackage -B

This will do everything to make architecture dependent binary packages on another architecture. It will:

- clean the source tree (`debian/rules clean`)

- build the program (`debian/rules build`)

- build architecture dependent binary packages (`fakeroot debian/rules binary-arch`)

- sign the source `.dsc` file, using gpg

- create and sign the upload `.changes` file, using dpkg-genchanges and gpg

This is why you see your package for other architectures.

Although packages listed in the `Build-Depends-Indep` field are required to be installed for our normal packaging work (see Section 6.1, “Complete (re)build”), they are not required to be installed for the autobuilder system since it builds only architecture dependent binary packages. [65] This distinction between normal packaging and autobuilding procedures is what dictates whether you should record such required packages in the `Build-Depends` or `Build-Depends-Indep` fields of the `debian/control` file (see Section 4.1, “`control`”).

## 6.3. debuild command

You can automate the build activity around executing the dpkg-buildpackage command package further with the debuild command. See debuild(1).

The debuild command executes the lintian command to make a static check after building the Debian package. The lintian command can be customized with the following in the `~/.devscripts` file:

    DEBUILD_DPKG_BUILDPACKAGE_OPTS="-us -uc -I -i"
    DEBUILD_LINTIAN_OPTS="-i -I --show-overrides"

Cleaning the source and rebuilding the package from your user account is as simple as:

    $ debuild

You can clean the source tree as simply as:

    $ debuild -- clean

## 6.4. `pbuilder` package

For a clean room (chroot) build environment to verify the build dependencies, the `pbuilder` package is very useful. [66] This ensures a clean build from the source under the `sid` auto-builder for different architectures and avoids a severity serious FTBFS (Fails To Build From Source) bug which is always in the RC (release critical) category. [67]

Let's customize the `pbuilder` package as follows:

- setting the `/var/cache/pbuilder/result` directory writable by your user account.

- creating a directory, e.g. ``/var/cache/pbuilder/hooks``, writable by the user, to place hook scripts in.

- configuring `~/.pbuilderrc` or `/etc/pbuilderrc` to include the following.

      AUTO_DEBSIGN=${AUTO_DEBSIGN:-no}
      HOOKDIR=/var/cache/pbuilder/hooks

First let's initialize the local `pbuilder` chroot system as follows:

    $ sudo pbuilder create

If you already have a completed source package, issue the following commands in the directory where the ``foo`.orig.tar.gz`, ``foo`.debian.tar.gz`, and ``foo`.dsc` files exist to update the local `pbuilder` chroot system and to build binary packages in it:

    $ sudo pbuilder --update
    $ sudo pbuilder --build foo_version.dsc

The newly built packages without the GPG signatures will be located in `/var/cache/pbuilder/result/` with non-root ownership.

The GPG signatures on the `.dsc` file and the `.changes` file can be generated as:

    $ cd /var/cache/pbuilder/result/
    $ debsign foo_version_arch.changes

If you have an updated source tree but have not generated the matching source package, issue the following commands in the source directory where the `debian` directory exists, instead:

    $ sudo pbuilder --update
    $ pdebuild

You can log into its chroot environment with the `pbuilder --login --save-after-login` command and configure it as you wish. This environment can be saved by leaving its shell prompt with `^D` (Control-D).

The latest version of the lintian command can be executed in the `chroot` environment using the hook script ``/var/cache/pbuilder/hooks`/B90lintian` configured as follows: [68]

    #!/bin/sh
    set -e
    install_packages() {
            apt-get -y --allow-downgrades install "$@"
            }
    install_packages lintian
    echo "+++ lintian output +++"
    su -c "lintian -i -I --show-overrides /tmp/buildd/*.changes" - pbuilder
    # use this version if you don't want lintian to fail the build
    #su -c "lintian -i -I --show-overrides /tmp/buildd/*.changes; :" - pbuilder
    echo "+++ end of lintian output +++"

You need to have access to the latest `sid` environment to build packages properly for `sid`. In practice, `sid` may be experiencing issues which makes it undesirable for you to migrate your whole system. The `pbuilder` package can help you to cope with this kind of situation.

You may need to update your `stable` packages after their release for `stable-proposed-updates`, `stable/updates`, etc. [69] For such occasions, the fact that you may be running a `sid` system is not a good enough excuse for failing to update them promptly. The `pbuilder` package can help you to access environments of almost any Debian derivative distribution of the same architecture.

See http://www.netfort.gr.jp/~dancer/software/pbuilder.html, pdebuild(1), pbuilderrc(5), and pbuilder(8).

## 6.5. git-buildpackage command and similar

If your upstream uses a source code management system (VCS) [70] to maintain their code, you should consider using it as well. This makes merging and cherry-picking upstream patches much easier. There are several specialized wrapper script packages for Debian package building for each VCS.

- `git-buildpackage`: a suite to help with Debian packages in Git repositories.

- `svn-buildpackage`: helper programs to maintain Debian packages with Subversion.

- `cvs-buildpackage`: a set of Debian package scripts for CVS source trees.

Use of `git-buildpackage` is becoming quite popular for Debian Developers to manage Debian packages with the Git server on alioth.debian.org. [71] This package offers many commands to automate packaging activities:

- gbp-import-dsc(1): import a previous Debian package to a Git repository.

- gbp-import-orig(1): import a new upstream tar to a Git repository.

- gbp-dch(1): generate the Debian changelog from Git commit messages.

- git-buildpackage(1): build Debian packages from a Git repository.

- git-pbuilder(1): build Debian packages from a Git repository using pbuilder/cowbuilder.

These commands use 3 branches to track packaging activity:

- `main` for Debian package source tree.

- `upstream` for upstream source tree.

- `pristine-tar` for upstream tarball generated by the `--pristine-tar` option.[72]

You can configure `git-buildpackage` with `~/.gbp.conf`. See gbp.conf(5). [73]

## 6.6. Quick rebuild

With a large package, you may not want to rebuild from scratch every time while you're tuning details in `debian/rules`. For testing purposes, you can make a `.deb` file without rebuilding the upstream sources like this[74]:

    $ fakeroot debian/rules binary

Or simply do the following to see if it builds or not:

    $ fakeroot debian/rules build

Once you are finished with your tuning, remember to rebuild following the proper procedure. You may not be able to upload correctly if you try to upload `.deb` files built this way.

## 6.7. Command hierarchy

Here is a quick summary of how many commands to build packages fit together in the command hierarchy. There are many ways to do the same thing.

- `debian/rules` = maintainer script for the package building

- dpkg-buildpackage = core of the package building tool

- debuild = dpkg-buildpackage + lintian (build under the sanitized environment variables)

- pbuilder = core of the Debian chroot environment tool

- pdebuild = pbuilder + dpkg-buildpackage (build in the chroot)

- cowbuilder = speed up the pbuilder execution

- git-pbuilder = the easy-to-use commandline syntax for pdebuild (used by gbp buildpackage)

- gbp = manage the Debian source under the git repo

- gbp buildpackage = pbuilder + dpkg-buildpackage + gbp

Although use of higher level commands such as gbp buildpackage and pbuilder ensures the perfect package building environment, it is essential to understand how lower level commands such as `debian/rules` and dpkg-buildpackage are executed under them.

[62] This GPG key must be signed by a Debian developer to get connected to the web of trust and must be registered to the Debian keyring. This enables your uploaded packages to be accepted to the Debian archives. See Creating a new GPG key and Debian Wiki on Keysigning.

[63] You can avoid applying quilt patches in the `3.0 (quilt)` source format at the end of the extraction with the `--skip-patches` option. Alternatively, you can run `dquilt pop -a` after normal operation.

[64] The actual autobuilder system involves much more complicated schemes than the one documented here. Such details are beyond the scope of this document.

[65] Unlike under the `pbuilder` package, the chroot environment under the `sbuild` package used by the autobuilder system does not enforce the use of a minimal system and may have many leftover packages installed.

[66] Since the `pbuilder` package is still evolving, you should check the actual configuration situation by consulting the latest official documentation.

[67] See http://buildd.debian.org/ for more on Debian package auto-building.

[68] This assumes `HOOKDIR=/var/cache/pbuilder/hooks`. You can find many examples of hook scripts in the `/usr/share/doc/pbuilder/examples` directory.

[69] There are some restrictions for such updates of your `stable` package.

[70] See Version control systems for more.

[71] Debian wiki Alioth documents how to use the alioth.debian.org service.

[72] The `--pristine-tar` option invokes the pristine-tar command, which can regenerate an exact copy of a pristine upstream tarball using only a small binary delta file and the contents of the tarball that are typically kept in an `upstream` branch in the VCS.

[73] Here are some web resources available for advanced audiences.

- Building Debian Packages with git-buildpackage (`/usr/share/doc/git-buildpackage/manual-html/gbp.html`)

- debian packages in git

- Using Git for Debian Packaging

- git-dpm: Debian packages in Git manager

[74] Environment variables that are normally configured to proper values are not set by this method. Never create real packages to be uploaded using this quick method.

Chapter 5. Other files under the `debian` directory |  | Chapter 7. Checking the package for errors