Debian packaging with CDBS

This document is a summary of what you need to know to do build Debian configuration packages. It is not intended to be a replacement for the official Debian documentation, but is instead an introduction to Debian development with a particular emphasis on describing in detail only the best ways to do each part of making a package (rather than starting from the underlying, annoying primitives) and on mentioning the commands and resources that are useful to know about.

This document assumes that packages you deal with are using CDBS and debhelper, and does not mention the more painful ways one can accomplish the same tasks without these tools.

Setup

You will also need tools to develop Debian packages. For generic Debian development, you should install the following Debian packages (on Debathena you can just aptitude install debathena-debian-dev or even aptitude install debathena-build-depends to get all build-dependencies of Debathena):

aptitude install build-essential cdbs debhelper wdiff \
    debian-el devscripts devscripts-el dh-make dpatch dpkg-awk \
    dpkg-dev dpkg-dev-el equivs fakeroot linda lintian quilt sbuild

The primary package compilation tool, debuild, will complain that you’re not signing builds with the package maintainer’s key unless you pass it the arguments debuild -us -uc -sa; you can add

DEBUILD_DPKG_BUILDPACKAGE_OPTS="-us -uc -sa -i -I"

to ~/.devscripts to not see these warnings and to not incorrectly include version control information in source packages. If you’re not running a distribution from 2008 or later, you should replace -I with -I.svn, where .svn is the extension for the version control system you’re using. You’ll also want to put your contact information in environment variables in ~/.bashrc (or equivalent):

export DEBEMAIL="tabbott@mit.edu"
export DEBFULLNAME="Tim Abbott"

If you’re planning to use quilt to patch packages, I recommend adding to your ~/.quiltrc:

QUILT_PATCHES=debian/patches

Building packages

To download and compile the source package corresponding to the libqd-dev binary package, you can simply run:

apt-get source libqd-dev
cd qd-version-dversion
debuild

Assuming you have the relevant build-dependencies installed (debuild will complain if they are not) and the build succeeds, this will result in a number of files being generated:

../spackage_version-dversion.diff.gz
A new Debian source package diff from the upstream tarball spackage_version.orig.tar.gz
../spackage_version-dversion.dsc
The new Debian source package description file.
../spackage_version-dversion.build
A copy of what was displayed on the screen during the build.
../spackage_version-dversion.changes
The changes file describes a possible upload to the Debian archive.
../bpackage_version-dversion_arch.deb
A resulting Debian binary package.

where version is the upstream version number for spackage, version-dversion is the Debian version number for spackage, arch is the architecture of the build machine, spackage is the name of the source package and bpackage is the name of a binary package from the source package (notice there’s more than one!).

You can inspect unpacked copies of your new packages in the debian/package subdirectories.

Whenever you build a package, you should check if any lintian errors or warnings were displayed at the end of the output. lintian is a fantastic system that checks for a number of common packaging mistakes. In the case of our example, qd, the build log from Debian etch contains several Lintian errors, all of which are actual bugs in the qd package. Debathena packages often generate changelog-should-mention-nmu, source-nmu-has-incorrect-version-number (both irrelevant since NMU’s are only meaningful in the Debian archive) and unknown-section (a result of the Debathena repository having different sections from the Debian archive). With CDBS, you sometimes also get a harmless package-has-a-duplicate-build-relation warning.

Making Debian packages

Structure of a source package

Every source package contains at least the following files:

debian/changelog
The Debian changelog for the package. The changelog is the authoritative source for the Debian version number of the package. It is typically installed to /usr/share/doc/package/changelog.Debian.gz. You should manage this with the dch command.
debian/compat
The debhelper compatibility level of the package. As of April 2013, it should contain a single line containing the number 7.
debian/control
The Debian packaging system’s metadata for the package. A brief reference is available at the end of this document. Note that while this can be auto-updated with CDBS from control.in, it is essential that it exists.
debian/control.in
CDBS packages will often have a file called debian/control.in that looks exactly like debian/control except that it has @cdbs@ as a build dependency. This is replaced with various build dependencies that CDBS knows about (like debhelper and cdbs) at build time to generate debian/control.
debian/copyright
A human-readable description of the copyright status of the package. /usr/share/debhelper/dh_make/licenses contains examples.
debian/rules
The executable makefile used to build the binary package.

The information in the table above (along with the control file reference at the end of this document) should be sufficient to generate the files mentioned so far aside from debian/rules, so we will focus attention on that. With CDBS, a simple package whose build system is based on autotools but where autoconf, automake, libtool, and aclocal should not be regenerated will probably look something like the following:

#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/autotools.mk

DEB_CONFIGURE_EXTRA_FLAGS := --enable-shared
# (this last line is from the qd package and is not generic)

For packages that use other build systems, there are rules files in /usr/share/cdbs/1/class/ for make, python-distutils, ant, and a few others. If you plan to use quilt patches, you’ll want to include /usr/share/cdbs/1/rules/patchsys-quilt.mk. CDBS is primarily controlled through the setting of make variables in the rules file or through the existence of special files in the debian directory. Many changes to flags passed to during the build process can be implemented by just setting a single variable. Many of these variables can also be set on a per-package basis using names like CFLAGS_package. To get a definitive answer, one should inspect the code of debhelper.mk or the class file that you are using. Below we list some of the more useful ones:

DEB_AUTO_UPDATE_DEBIAN_CONTROL
Set this to enabled auto-generation of debian/control from debian/control.in. This option is basically banned in Debian because it apparently causes problems with NMUs, but it can save work.
DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk)
Any extra flags you want to pass to configure.
DEB_MAKE_ENVVARS (makefile.mk)
Any environment variables you want to set for make.
DEB_MAKE_INVOKE += … (makefile.mk)
Pass extra flags to make (note the += here).
DEB_MAKE_{BUILD,CLEAN,…}_TARGET (makefile.mk)
Control what make targets CDBS uses. Note that make install and make check unless you set their corresponding target variable.
DEB_MAKE_CLEAN_TARGET (makefile.mk)
Often you want to set this to distclean.
CFLAGS,CPPFLAGS,LDFLAGS,… (makefile.mk)
Control common compiler and linker flags.
DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk)
Any extra flags you want to pass to configure.
DEB_AUTO_UPDATE_AUTOAUTO = version (makefile.mk)
Have autotools component AUTOAUTO-version run at build time.
DEB_DH_LINK_ARGS
Create symlinks in your installation.
DEB_DH_debhelper-tool_ARGS
Add flags to any of a number of debhelper tools.

Many simple tasks, such as installing an init script for your package can be handled easily be just creating the relevant file (CDBS is automatically invoking debhelper to do this). Below is a list of some of the more useful ones; for a complete list, read debhelper.mk:

debian/package.install
Pairs, one per line, of files and directories to install them to. Understands “*” and copies directories recursively.
debian/package.init
The package’s init script. Code to run update-rc.d and run the init script at package installation and removal is automatically added to maintainer scripts.
debian/package.cron.d
cron job to be automatically installed into /etc/cron.d.
debian/package.docs
List documentation files/directories to be automatically installed into /usr/share/doc/package.
debian/package.dirs
List directories to be automatically created.
debian/package.postinst
The package’s postinst maintainer script. Make sure you include #DEBHELPER# in maintainer scripts and handle all the right arguments. The best way to do this is to start from /usr/share/debhelper/dh_make/debian/postinst.ex.

Below are a number of tables of commands and information sources that should help you get all the information you need to make packages using CDBS. However, you probably should look at some more examples and probably need some practice. Plentiful examples are available in the CDBS gallery and the Debathena source tree; for practice, a good exercise is to pick a random package, delete its debian/rules file, and try to get it working using CDBS.

Useful commands

Below we list various commands that are frequently useful when doing Debian packaging:

apt-get source package
Download and unpack a Debian source package.
dpkg-source -x foo.dsc
Unpack a Debian source package (a common operation for source packages downloaded from packages.debian.org).
debuild
Build Debian source and binary packages from the root of an unpacked Debian source tree.
debuild -S
Build only the source package.
debuild -b
Build only the binary package.
debuild clean
Clean up a Debian source tree.
dch [-i]
Add an item to the Debian changelog. Use -i to also increment the version number (potentially renaming the current directory).
dpkg -i foo.deb
install a binary package
apt-get install package
install package from an apt repository.
dpkg -I foo.deb
View package control information.
dpkg -c foo.deb
List of files in package.
dpkg -x foo.deb dir
Extract the package into directory dir.
dpkg -e foo.deb dir
Extract Debian metadata (control file, maintainer scripts, md5sums, etc.) to directory dir.
apt-cache show package
Display control information for package.
apt-cache search keywords
Display a list of packages whose names or descriptions match keywords.
aptitude search ~Dpackage
List all packages in Debian that Depends: package. Other searches are possible as well:

aptitude search ~DRecommends:package finds packages that Recommends: package.
dpkg -l [package]
List packages installed on the system, and their version numbers. If package is provided, only list information for package.
dpkg -L package
List the files in installed package package.
dpkg -S filename
List installed packages that contain filename.
apt-file search filename
List all packages in Debian that contain filename. This command is slow.
reprepro
For setting up APT repositories.
reportbug
CLI to report a bug in Debian. It asks you questions and then sends an email.
equivs-build

equivs-control
equivs is a tool for creating Debian packages that contain only dependency information. It is useful for creating metapackages and for creating dummy packages to cause dpkg to ignore a dependency.
dpkg-divert --list
List diversions. The config-package-dev system uses these.
dpkg-awk
Useful for doing advanced queries on the list of all packages.
dpkg-depcheck
Guess runtime dependencies of a package using strace. (dpkg -L devscripts | grep bin is a good resources for finding this kind of thing).
dpkg-reconfigure package
Reconfigure package by re-running its postinst script with options set to ask all the debconf questions.
debconf-get-selections

debconf-set-selections
Commands for interacting with the debconf database.



dh_make -c gpl -b -r
Create a new template Debian package for a GPL-licensed piece of software using CDBS, and create a .orig.tar.gz from the current working directory. This should be run from the root directory of the relevant upstream source, and this directory should be called package-version. If the package is Debian-native, pass -n rather than -r.
quilt
quilt is a useful system for generating patch sets. The Ubuntu packaging guide documents how to use it. If you’re using AFS, you will use quilt refresh and quilt pop -a frequently. Remember to include /usr/share/cdbs/1/rules/patchsys-quilt.mk in your debian/rules file.

Useful sources of information

Below are a list of files and URLs that we frequently inspect when doing Debian development.

/var/lib/dpkg/info/package.postinst
The postinst script for package. Other maintainer scripts (preinst, prerm, and postrm are named similarly.
/var/lib/dpkg/info/package.conffiles
The list of conffiles (configuration files not managed by debconf, Debian’s system for prompting the user) and their md5sums for package.
/var/lib/dpkg/info/package.md5sums
The md5sums of the non-conffiles in package. Approximately 400 of the 18000 Debian packages fail to ship these.
/var/lib/dpkg/status
The control information for all packages currently installed on the system. If you break dpkg so that you have some package which is half-installed but cannot be either installed or removed, then editing this file may be a way to uninstall the package. Don’t mess with it lightly.
/usr/share/doc/package/changelog.gz

/usr/share/doc/package/changelog.Debian.gz
The Debian changelog for package. Useful to investigating when some behavior changed.
/usr/share/cdbs/1/rules/*.mk
The CDBS core rules files. Inspecting these (especially debhelper.mk and buildcore.mk) can help figure out how to add additional operations to your package’s build process or pass arguments to debhelper.
/usr/share/cdbs/1/class/*.mk
The CDBS rules files for various build systems. Inspecting the rules files that you are using (often makefile*.mk or autotools*.mk) can be helpful for figuring out how to do various supported things like pass additional make or configure flags.
http://packages.debian.org/package
Debian packages page for package. Lists what version of package is available in each version of Debian, and for each such distribution links to the bug reports, changelog, source package, and binary package files for that version.
http://packages.ubuntu.com/package
Ubuntu packages page for package (similar to above).
http://bugs.debian.org/package
Debian bugs reported against package.
https://launchpad.net/ubuntu/+source

/package/+bugs
Ubuntu bugs reported against package.



/usr/share/doc/cdbs/cdbs-doc.html
CDBS Documentation. Contains documentation on the variables to use to configure the various classes, example, etc.
Debian New Maintainers Guide
Debian’s documentation for new developers. Recommended reading.
Ubuntu Packaging Guide’s CDBS section
This is good documentation for doing autotools and python packages with CDBS. You may also want to read the page describing copyright and control files
Debian Policy Manual
Debian policy. Extensive. Has the precise definitions of each of the control fields and maintainer scripts.
Debian Developer’s Reference
Debian Developer’s reference.
Filesystem Hierarchy Standard
Useful for deciding where a particular file should be installed on a Debian machine.

The debian/control file

The follow table describes the fields in debian/control; look at the debian/control file for any package to learn the format. The formal definitions of these fields are all available in Debian policy. The first few should go under the Source: spackage heading; the others should go under the individual Package: bpackage headings. Section sometimes appears in both places.

Priority
Used by aptitude to decide what to keep when there are conflicts. You want to set this to optional. Setting it to required is a way to make it hard to remove your package with aptitude.
Section
The Section is mostly irrelevant; copy it from a package similar to yours. This field has a special format, section/subsection. The section part determines what component of a Debian repository (i.e. the things after the name of the distro in the /etc/apt/sources.list line) to upload the package to (in standard Debian, main, contrib, or non-free; in Debathena, debathena, debathena-standard, debathena-system, or openafs); if it is not specified the section is assumed to be main. The subsection field is simply used for organizing graphical user interfaces to the Debian archive.
Standards-Version
Used by Lintian. Get it using apt-cache show debian-policy | grep Version.
Maintainer
Your contact information, e.g. Tim Abbott <tabbott@mit.edu>
Build-Depends
List packages needed to build your package. You don’t need to include any Priority: essential packages or anything depended on by build-essential.
Architecture
If your package is architecture-independent (e.g. a shell script), you want “all”. If your package only works on some architectures, list those architectures. Otherwise, you want “any”.
Depends
A hard dependency; the package will not be installed unless the packages it depends on are installed. Necessary shared libraries should be automatically added if you include “${shlibs:Depends}”. Other useful dependencies may be added by debhelper if you include “${misc:Depends}”. You don’t need to include any Priority: essential packages.
Recommends
A soft dependency; aptitude and recent apt-get will prompt you to install the recommended packages along with your package, but they will let you install your package without its recommended packages.
Suggests
A dependency that doesn’t do anything.
Conflicts
A dependency that prevents both packages from being installed simultaneously.
Provides
Assign virtual names to the package. Debian uses this for defining alternatives (e.g. mail-transport-agent is anything providing sendmail), but Provides is useful for many other applications.
Replaces
When one package replaces or is a renaming of another, you want to specify Replaces: and Conflicts: against that package. Files from the named packages will be overwritten with the files from your package and it’ll make aptitude happier about the upgrade.
Pre-Depends, Breaks
These are stronger versions of Depends and Conflicts. Avoid using them.
Description
A description of the package in a weird format. Look at examples or see Debian policy.

Systems and concepts worth understanding

Debconf
Debconf is the Debian configuration system. It is the only way Debian packages are allowed to request user input during the installation process (and is typically invoked by the db_get and similar functions in the package’s postinst script. Feeding debconf is the standard way to make custom Debian install CDs.
conffiles
Configuration files (i.e. files under /etc) not managed by debconf and postinst scripts.
maintainer scripts
The preinst, postinst, prerm and postrm scripts that are run automatically when the package is either installed or removed.
Lintian
Lintian tells you what common probable mistakes you made in making your Debian package. It is an extremely useful tool for catching bugs in your packages. debuild runs lintian automatically after building a package.
Debhelper
Debhelper is a system of perl scripts that handle many tasks in making a Debian package, such as generating md5sums, automatically installing init scripts correctly, gzipping man pages, stripping libraries, byte-compiling python modules, etc. CDBS runs all the relevant Debhelper scripts by default.
Debian-Native Packages
Packages that exist only in Debian and are only useful in Debian are Debian-native; they differ from other packages primarily in that they only have one version number and the source packages for them consist of only a .tar.gz and a .dsc file, rather than a .orig.tar.gz, a .diff.gz, and a .dsc file.