Debian packaging with CDBS

http://debathena.mit.edu/packaging/

Debian packaging with CDBS

This document is a summary of what you need to know to do build Debian conguration packages. It is not intended to be a replacement for the ocial 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 builddependencies 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 youre not signing builds with the package maintainers 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 youre 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 youre using. Youll also want to put your contact information in environment variables in ~/.bashrc (or equivalent): export DEBEMAIL="tabbott@mit.edu" export DEBFULLNAME="Tim Abbott" If youre 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 les being generated:

1 of 8

Saturday 05 November 2011 12:29 AM

Debian packaging with CDBS

http://debathena.mit.edu/packaging/

../spackage_version-dversion.di.gz

A new Debian source package di from the upstream tarball spackage_version.orig.tar.gz The new Debian source package description le. A copy of what was displayed on the screen during the build. The changes le describes a possible upload to the Debian archive. A resulting Debian binary package.

../spackage_version-dversion.dsc ../spackage_version-dversion.build ../spackage_version-dversion.changes ../bpackage_version-dversion_arch.deb

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 theres 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-incorrectversion-number (both irrelevant since NMUs are only meaningful in the Debian archive) and unknown-section (a result of the Debathena repository having dierent sections from the Debian archive). With CDBS, you sometimes also get a harmless package-has-a-duplicatebuild-relation warning.

Making Debian packages Structure of a source package

Every source package contains at least the following les: 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. The debhelper compatability level of the package. It should contain a single line containing the number 5. The Debian packaging systems 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. CDBS packages will often have a le 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. A human-readable description of the copyright status of the package. /usr/share/debhelper/dh_make/licenses contains examples.

debian/compat debian/control

debian/control.in

debian/copyright

2 of 8

Saturday 05 November 2011 12:29 AM

Debian packaging with CDBS

http://debathena.mit.edu/packaging/

debian/rules

The executable makele used to build the binary package.

The information in the table above (along with the control le reference at the end of this document) should be sucient to generate the les 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 les in /usr/share/cdbs/1/class/ for make, python-distutils, ant, and a few others. If you plan to use quilt patches, youll want to include /usr/share/cdbs/1/rules/patchsys-quilt.mk. CDBS is primarily controlled through the setting of make variables in the rules le or through the existence of special les in the debian directory. Many changes to ags 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 denitive answer, one should inspect the code of debhelper.mk or the class le 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. Any extra ags you want to pass to congure. Any environment variables you want to set for make. Pass extra ags to make (note the += here).

DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk) DEB_MAKE_ENVVARS (makefile.mk) DEB_MAKE_INVOKE += (makefile.mk)

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) CFLAGS,CPPFLAGS,LDFLAGS, (makefile.mk) DEB_CONFIGURE_EXTRA_FLAGS (autotools.mk) Often you want to set this to distclean. Control common compiler and linker ags. Any extra ags you want to pass to congure.

DEB_AUTO_UPDATE_AUTOAUTO = version (makefile.mk)Have autotools component AUTOAUTOversion run at build time. DEB_DH_LINK_ARGS DEB_DH_debhelper-tool_ARGS Create symlinks in your installation. Add ags 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

3 of 8

Saturday 05 November 2011 12:29 AM

Debian packaging with CDBS

http://debathena.mit.edu/packaging/

just creating the relevant le (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 les and directories to install them to. Understands * and copies directories recursively. The packages init script. Code to run update-rc.d and run the init script at package installation and removal is automatically added to maintainer scripts. cron job to be automatically installed into /etc/cron.d. List documentation les/directories to be automatically installed into /usr/share /doc/package. List directories to be automatically created. The packages 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.

debian/package.init

debian/package.cron.d debian/package.docs

debian/package.dirs debian/package.postinst

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 le, 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 dpkg-source -x foo.dsc debuild debuild -S debuild -b debuild clean dch [-i] dpkg -i foo.deb apt-get install package dpkg -I foo.deb dpkg -c foo.deb dpkg -x foo.deb dir dpkg -e foo.deb dir Download and unpack a Debian source package. Unpack a Debian source package (a common operation for source packages downloaded from packages.debian.org). Build Debian source and binary packages from the root of an unpacked Debian source tree. Build only the source package. Build only the binary package. Clean up a Debian source tree. Add an item to the Debian changelog. Use -i to also increment the version number (potentially renaming the current directory). install a binary package install package from an apt repository. View package control information. List of les in package. Extract the package into directory dir. Extract Debian metadata (control le, maintainer scripts,

4 of 8

Saturday 05 November 2011 12:29 AM

Debian packaging with CDBS

http://debathena.mit.edu/packaging/

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 nds packages that Recommends: package. dpkg -l [package] dpkg -L package dpkg -S filename List packages installed on the system, and their version numbers. If package is provided, only list information for package. List the les in installed package package. List installed packages that contain lename.

apt-file search filename List all packages in Debian that contain lename. This command is slow. reprepro reportbug equivs-build equivs-control For setting up APT repositories. CLI to report a bug in Debian. It asks you questions and then sends an email. 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. List diversions. The config-package-dev system uses these. Useful for doing advanced queries on the list of all packages. Guess runtime dependencies of a package using strace. (dpkg -L devscripts | grep bin is a good resources for nding this kind of thing).

dpkg-divert --list dpkg-awk dpkg-depcheck

dpkg-reconfigure package Recongure package by re-running its postinst script with options set to ask all the debconf questions. debconf-get-selections debconf-set-selections dh_make -c gpl -b -r Commands for interacting with the debconf database. 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 is a useful system for generating patch sets. The Ubuntu packaging guide documents how to use it. If youre 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 le.

quilt

Useful sources of information

Below are a list of les 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

5 of 8

Saturday 05 November 2011 12:29 AM

Debian packaging with CDBS

http://debathena.mit.edu/packaging/

postrm are named similarly. /var/lib/dpkg/info/package.conffiles The list of conffiles (conguration les not managed by debconf, Debians system for prompting the user) and their md5sums for package. The md5sums of the non-conles in package. Approximately 400 of the 18000 Debian packages fail to ship these. 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 le may be a way to uninstall the package. Dont mess with it lightly. The Debian changelog for package. Useful to investigating when some behavior changed. The CDBS core rules les. Inspecting these (especially debhelper.mk and buildcore.mk) can help gure out how to add additional operations to your packages build process or pass arguments to debhelper. The CDBS rules les for various build systems. Inspecting the rules les that you are using (often makele*.mk or autotools*.mk) can be helpful for guring out how to do various supported things like pass additional make or congure ags. 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 les for that version. Ubuntu packages page for package (similar to above). Debian bugs reported against package. Ubuntu bugs reported against package. CDBS Documentation. Contains documentation on the variables to use to congure the various classes, example, etc. Debians documentation for new developers. Recommended reading. This is good documentation for doing autotools and python packages with CDBS. You may also want to read the page

/var/lib/dpkg/info/package.md5sums

/var/lib/dpkg/status

/usr/share/doc/package/changelog.gz /usr/share/doc/package/changelog.Debian.gz /usr/share/cdbs/1/rules/*.mk

/usr/share/cdbs/1/class/*.mk

http://packages.debian.org/package

http://packages.ubuntu.com/package http://bugs.debian.org/package https://launchpad.net/ubuntu/+source /package/+bugs /usr/share/doc/cdbs/cdbs-doc.html

Debian New Maintainers Guide Ubuntu Packaging Guides CDBS section

6 of 8

Saturday 05 November 2011 12:29 AM

Debian packaging with CDBS

http://debathena.mit.edu/packaging/

describing copyright and control les Debian Policy Manual Debian policy. Extensive. Has the precise denitions of each of the control elds and maintainer scripts. Debian Developers reference. Useful for deciding where a particular le should be installed on a Debian machine.

Debian Developers Reference Filesystem Hierarchy Standard

The debian/control file

The follow table describes the elds in debian/control; look at the debian/control le for any package to learn the format. The formal denitions of these elds are all available in Debian policy. The rst 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 conicts. You want to set this to optional. Setting it to required is a way to make it hard to remove your package with aptitude. The Section is mostly irrelevant; copy it from a package similar to yours. This eld 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 specied the section is assumed to be main. The subsection eld is simply used for organizing graphical user interfaces to the Debian archive. Used by Lintian. Get it using apt-cache show debian-policy | grep Version. Your contact information, e.g. Tim Abbott <tabbott@mit.edu> List packages needed to build your package. You dont need to include any Priority: essential packages or anything depended on by build-essential. 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. 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 dont need to include any Priority: essential packages. 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. A dependency that doesnt do anything. A dependency that prevents both packages from being installed simultaneously.

Section

Standards-Version Maintainer Build-Depends

Architecture

Depends

Recommends

Suggests Conicts

7 of 8

Saturday 05 November 2011 12:29 AM

Debian packaging with CDBS

http://debathena.mit.edu/packaging/

Provides

Assign virtual names to the package. Debian uses this for dening alternatives (e.g. mail-transport-agent is anything providing sendmail), but Provides is useful for many other applications. When one package replaces or is a renaming of another, you want to specify Replaces: and Conicts: against that package. Files from the named packages will be overwritten with the les from your package and itll make aptitude happier about the upgrade. These are stronger versions of Depends and Conicts. Avoid using them. A description of the package in a weird format. Look at examples or see Debian policy.

Replaces

Pre-Depends, Breaks Description

Systems and concepts worth understanding

Debconf Debconf is the Debian conguration 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 packages postinst script. Feeding debconf is the standard way to make custom Debian install CDs. Conguration les (i.e. les under /etc) not managed by debconf and postinst scripts. The preinst, postinst, prerm and postrm scripts that are run automatically when the package is either installed or removed. 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 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. Packages that exist only in Debian and are only useful in Debian are Debian-native; they dier 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 le, rather than a .orig.tar.gz, a .diff.gz, and a .dsc le.

conles maintainer scripts Lintian

Debhelper

Debian-Native Packages

8 of 8

Saturday 05 November 2011 12:29 AM