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.