The Debian build toolchain is a collection of software utilities used to create Debian source packages (<code>.dsc</code>) and Debian binary packages (<code>.deb</code> files) from upstream source tarballs.
These tools are used in the Debian project and also in Debian-based distributions such as Ubuntu.
Source code for free software is typically distributed in compressed tar archives called tarballs. Debian is a binary-oriented distribution, meaning that its <code>deb</code> packages include precompiled binaries and data files arranged into a file system hierarchy that the software expects. The Debian build toolchain thus needs instructions on how to use the upstream build system to build correct <code>deb</code> packages.
These instructions are stored in the <code>debian</code> subdirectory, which is added to the source tree for the software being packaged by the package maintainer. While it is possible to build the package directly from the modified source tree, it is standard practice to create source packages, which contain the changes the maintainer made to the upstream sources in redistributable form.
A typical Debian source package consists of three files:
For example, a source package named <code>foo</code> with upstream version 1.2.3 and Debian revision 4 can consist of the following files:
A source package is created using the <code>dpkg-buildpackage</code> tool or its wrapper <code>debuild</code>. When invoked to create a source package, <code>dpkg-buildpackage</code> calls the maintainer's rules to clean the source tree of any intermediate files, does various sanity checks, and finally, signs the <code>dsc</code> file with the packager's key using the <code>debsign</code> utility.
The reverse process — producing the unpacked source tree from a source package — is accomplished using the <code>dpkg-source</code> utility, which extracts the original tarball to a subdirectory, extracts the <code>debian.tar</code> tarball inside it, and applies any quilt patches present. This is the first step that a build system does when building binary packages from a source package.
Older source packages (using Source Format 1) have a <code>.diff.gz</code> file instead of the <code>debian.tar</code>. This is a unified diff that contains the <code>debian</code> directory and any changes to the upstream source that aren't managed by a patch system.
The debian directory contains files used by <code>dpkg-buildpackage</code> to create both binary and source packages. Unlike RPM, which uses a single <code>spec</code> file for instructions, the Debian tools use an entire subdirectory with multiple files. Three files are required at minimum to correctly build a package — <code>changelog</code>, <code>control</code> and <code>rules</code>. A fourth file, <code>copyright</code>, is mandated by the Debian policy, but is a legal requirement rather than a technical one.
By design, all files in the <code>debian</code> directory are text files, most of which are human-readable and edited with a simple text editor.
This file contains information about all versions of the package since it was created. The build tools only process the top entry, which is used to determine the package version, urgency (which is only of relevance to Debian itself), and bugs in the distribution that this release fixes.
For example, for a package named <code>foo</code>, an example <code>debian/changelog</code> entry can read like this:
Debian provides two main utilities for manipulating the <code>debian/changelog</code> file:
This file contains information about the source package and all binary packages it builds (there can be more than one; for example, the source package <code>libbar</code> can serve as the source for binary packages <code>libbar0</code>, which contains just the shared library, and <code>libbar-dev</code>, which contains a static version of the library and header files).
It lists (among others) such things as the package name, maintainer, target architectures (for binary packages), build dependencies (packages that must be installed for the package to successfully build) and dependencies (packages that must be installed for the package to function properly when installed).
This file is a script that is invoked by <code>dpkg-buildpackage</code> with a single argument that specifies the action to take (<code>clean</code>, <code>build</code>, <code>install</code>, <code>binary</code>). Although it can technically be any kind of script, it is always implemented as a makefile.
Apart from invoking the upstream build system, most instructions in <code>debian/rules</code> are highly repetitive and ubiquitous, and thus, virtually all <code>debian/rules</code> files wrap this functionality in debhelper scripts. For example, automatically determining the dependencies based on shared libraries used is a very common action, and thus, instead of including the code necessary to do it, the <code>debian/rules</code> file simply calls <code>dh_shlibdeps</code>. Other examples of debhelper scripts include <code>dh_installdocs</code>, which installs stock documentation files such as <code>debian/copyright</code> into their appropriate locations, or <code>dh_fixperms</code>, which ensures that files in the package have correct access rights (for example, executables in <code>/usr/bin</code> have the "executable" bit set, but are only writable by the superuser).
Since sequences of <code>debhelper</code> scripts are themselves repetitive, some packages simplify <code>debian/rules</code> files directly by using dh or CDBS instead of running each <code>debhelper</code> command directly.
Sometimes, a maintainer needs to modify the original source. While, in the past, this was often done simply by editing the files in place and including the changes in the <code>diff.gz</code>, this could make maintenance difficult when new upstream versions were released, because all the changes had to be examined and merged when necessary.
The newer source format, 3.0 (quilt), uses the quilt patch system, to allow the modifications to be broken into groups of logically separated patches, each of which deals with one change and can be sent upstream as is. These patches live in <code>debian/patches</code>.
There are also packages using other patch systems, such as <code>dpatch</code>. It generates and executes shell scripts that are non-standard unified diff files with a header, which nevertheless are compatible with the standard <code>diff</code> utility. The <code>debian/rules</code> file is modified to call <code>dpatch apply-all</code> before building the binary package and <code>dpatch deapply-all</code> before building the source package (and cleaning up any build byproducts). <code>quilt</code> and certain other patch systems eliminate the need for special headers and use standard diff files.
Sometimes a user may want to look at differences between two source packages — for example, to generate a proposed patch against the version currently in the repository for inclusion in the distribution's bug tracking system. If both packages use the same upstream version, this can done using the <code>debdiff</code> tool, which produces differences between two source trees with packaging changes included.
If the upstream tarballs for the two versions are different, such a naive comparison cannot be used. Instead, the <code>interdiff</code> utility can be used to produce a diff between two diff files (in this case, between two <code>diff.gz</code> files). A drawback is that an <code>interdiff</code> output requires more effort to apply, and the one applying the changes must also find and download the newer upstream tarball, which is typically done using the <code>get-orig-source</code> rule in <code>debian/rules</code>.
This tool provides automated checks for common packaging mistakes in both binary and source packages, including Debian policy violations and potential compatibility problems.
While a maintainer typically aims to correct all issues pointed out by , different distributions can have different policies regarding them. For example, Ubuntu requires all packages originating in Ubuntu to be clean, but for a package merged into Ubuntu from Debian, there is no such requirement: new changes should simply not introduce any warnings in addition to existing ones. This is done to minimize the divergence between Debian and Ubuntu packages.
Here are example outputs: <div class="plainlinks">
</div>
Source packages are intended to be buildable on any installation of the target distribution version, provided that build dependencies are met. In addition, builds can be affected by packages already present in the system.
To verify that a package builds on any system, and to exclude any external factors, tools to create isolated build environments are used. These are <code>pbuilder</code> (Personal Builder) and <code>sbuild</code>.
These tools maintain minimal working systems in chroot, install only the necessary build dependencies listed in <code>debian/control</code>, and remove them when the build is finished. Therefore, using <code>pbuilder</code>, a package maintainer can detect if some build dependencies were not specified in <code>debian/control</code>. Also, <code>pbuilder</code> makes it possible to test-build for distributions other than the one the maintainer is running: for example, for the development version, while actually running the stable version.
<code>sbuild</code> is designed for integration with automated build daemons (<code>buildd</code>). It is used by Debian build servers, which automatically build binary packages for every supported architecture. The Launchpad service provides similar build daemons for Ubuntu, both the official distribution and personal package archives (PPAs).