Appendix A. Overview of Debian Maintainer Tools

Table of Contents

A.1. Core tools
A.1.1. dpkg-dev
A.1.2. debconf
A.1.3. fakeroot
A.2. Package lint tools
A.2.1. lintian
A.2.2. debdiff
A.3. Helpers for debian/rules
A.3.1. debhelper
A.3.2. dh-make
A.3.3. equivs
A.4. Package builders
A.4.1. git-buildpackage
A.4.2. debootstrap
A.4.3. pbuilder
A.4.4. sbuild
A.5. Package uploaders
A.5.1. dupload
A.5.2. dput
A.5.3. dcut
A.6. Maintenance automation
A.6.1. devscripts
A.6.2. autotools-dev
A.6.3. dpkg-repack
A.6.4. alien
A.6.5. debsums
A.6.6. dpkg-dev-el
A.6.7. dpkg-depcheck
A.7. Porting tools
A.7.1. quinn-diff
A.7.2. dpkg-cross
A.8. Documentation and information
A.8.1. docbook-xml
A.8.2. debiandoc-sgml
A.8.3. debian-keyring
A.8.4. debian-maintainers
A.8.5. debview

This section contains a rough overview of the tools available to maintainers. The following is by no means complete or definitive, but just a guide to some of the more popular tools.

Debian maintainer tools are meant to aid developers and free their time for critical tasks. As Larry Wall says, there's more than one way to do it.

Some people prefer to use high-level package maintenance tools and some do not. Debian is officially agnostic on this issue; any tool which gets the job done is fine. Therefore, this section is not meant to stipulate to anyone which tools they should use or how they should go about their duties of maintainership. Nor is it meant to endorse any particular tool to the exclusion of a competing tool.

Most of the descriptions of these packages come from the actual package descriptions themselves. Further information can be found in the package documentation itself. You can also see more info with the command apt-cache show package-name.

A.1. Core tools

The following tools are pretty much required for any maintainer.

A.1.1. dpkg-dev

dpkg-dev contains the tools (including dpkg-source) required to unpack, build, and upload Debian source packages. These utilities contain the fundamental, low-level functionality required to create and manipulate packages; as such, they are essential for any Debian maintainer.

A.1.2. debconf

debconf provides a consistent interface to configuring packages interactively. It is user interface independent, allowing end-users to configure packages with a text-only interface, an HTML interface, or a dialog interface. New interfaces can be added as modules.

You can find documentation for this package in the debconf-doc package.

Many feel that this system should be used for all packages which require interactive configuration; see Section 6.5, “Configuration management with debconf. debconf is not currently required by Debian Policy, but that may change in the future.

A.1.3. fakeroot

fakeroot simulates root privileges. This enables you to build packages without being root (packages usually want to install files with root ownership). If you have fakeroot installed, you can build packages as a regular user: dpkg-buildpackage -rfakeroot.

A.2. Package lint tools

According to the Free On-line Dictionary of Computing (FOLDOC), `lint' is a Unix C language processor which carries out more thorough checks on the code than is usual with C compilers. Package lint tools help package maintainers by automatically finding common problems and policy violations in their packages.

A.2.1. lintian

lintian dissects Debian packages and emits information about bugs and policy violations. It contains automated checks for many aspects of Debian policy as well as some checks for common errors.

You should periodically get the newest lintian from unstable and check over all your packages. Notice that the -i option provides detailed explanations of what each error or warning means, what its basis in Policy is, and commonly how you can fix the problem.

Refer to Section 5.3, “Testing the package” for more information on how and when to use Lintian.

You can also see a summary of all problems reported by Lintian on your packages at http://lintian.debian.org/. These reports contain the latest lintian output for the whole development distribution (unstable).

A.2.2. debdiff

debdiff (from the devscripts package, Section A.6.1, “devscripts) compares file lists and control files of two packages. It is a simple regression test, as it will help you notice if the number of binary packages has changed since the last upload, or if something has changed in the control file. Of course, some of the changes it reports will be all right, but it can help you prevent various accidents.

You can run it over a pair of binary packages:

debdiff package_1-1_arch.deb package_2-1_arch.deb

Or even a pair of changes files:

debdiff package_1-1_arch.changes package_2-1_arch.changes

For more information please see debdiff(1).

A.3. Helpers for debian/rules

Package building tools make the process of writing debian/rules files easier. See Section 6.1.1, “Helper scripts” for more information about why these might or might not be desired.

A.3.1. debhelper

debhelper is a collection of programs which can be used in debian/rules to automate common tasks related to building binary Debian packages. debhelper includes programs to install various files into your package, compress files, fix file permissions, and integrate your package with the Debian menu system.

Unlike some approaches, debhelper is broken into several small, simple commands which act in a consistent manner. As such, it allows more fine-grained control than some of the other debian/rules tools.

There are a number of little debhelper add-on packages, too transient to document. You can see the list of most of them by doing apt-cache search ^dh-.

A.3.2. dh-make

The dh-make package contains dh_make, a program that creates a skeleton of files necessary to build a Debian package out of a source tree. As the name suggests, dh_make is a rewrite of debmake and its template files use dh_* programs from debhelper.

While the rules files generated by dh_make are in general a sufficient basis for a working package, they are still just the groundwork: the burden still lies on the maintainer to finely tune the generated files and make the package entirely functional and Policy-compliant.

A.3.3. equivs

equivs is another package for making packages. It is often suggested for local use if you need to make a package simply to fulfill dependencies. It is also sometimes used when making ``meta-packages'', which are packages whose only purpose is to depend on other packages.

A.4. Package builders

The following packages help with the package building process, general driving dpkg-buildpackage as well as handling supporting tasks.

A.4.1. git-buildpackage

git-buildpackage provides the capability to inject or import Debian source packages into a Git repository, build a Debian package from the Git repository, and helps in integrating upstream changes into the repository.

These utilities provide an infrastructure to facilitate the use of Git by Debian maintainers. This allows one to keep separate Git branches of a package for stable, unstable and possibly experimental distributions, along with the other benefits of a version control system.

A.4.2. debootstrap

The debootstrap package and script allows you to bootstrap a Debian base system into any part of your filesystem. By base system, we mean the bare minimum of packages required to operate and install the rest of the system.

Having a system like this can be useful in many ways. For instance, you can chroot into it if you want to test your build dependencies. Or you can test how your package behaves when installed into a bare base system. Chroot builders use this package; see below.

A.4.3. pbuilder

pbuilder constructs a chrooted system, and builds a package inside the chroot. It is very useful to check that a package's build-dependencies are correct, and to be sure that unnecessary and wrong build dependencies will not exist in the resulting package.

A related package is cowbuilder, which speeds up the build process using COW filesystem on any standard Linux filesystem.

A.4.4. sbuild

sbuild is another automated builder. It can use chrooted environments as well. It can be used stand-alone, or as part of a networked, distributed build environment. As the latter, it is part of the system used by porters to build binary packages for all the available architectures. See Section 5.10.3.3, “wanna-build for more information, and http://buildd.debian.org/ to see the system in action.

A.5. Package uploaders

The following packages help automate or simplify the process of uploading packages into the official archive.

A.5.1. dupload

dupload is a package and a script to automatically upload Debian packages to the Debian archive, to log the upload, and to send mail about the upload of a package. You can configure it for new upload locations or methods.

A.5.2. dput

The dput package and script does much the same thing as dupload, but in a different way. It has some features over dupload, such as the ability to check the GnuPG signature and checksums before uploading, and the possibility of running dinstall in dry-run mode after the upload.

A.5.3. dcut

The dcut script (part of the package dput, Section A.5.2, “dput) helps in removing files from the ftp upload directory.

A.6. Maintenance automation

The following tools help automate different maintenance tasks, from adding changelog entries or signature lines and looking up bugs in Emacs to making use of the newest and official config.sub.

A.6.1. devscripts

devscripts is a package containing wrappers and tools which are very helpful for maintaining your Debian packages. Example scripts include debchange and dch, which manipulate your debian/changelog file from the command-line, and debuild, which is a wrapper around dpkg-buildpackage. The bts utility is also very helpful to update the state of bug reports on the command line. uscan can be used to watch for new upstream versions of your packages. debrsign can be used to remotely sign a package prior to upload, which is nice when the machine you build the package on is different from where your GPG keys are.

See the devscripts(1) manual page for a complete list of available scripts.

A.6.2. autotools-dev

autotools-dev contains best practices for people who maintain packages which use autoconf and/or automake. Also contains canonical config.sub and config.guess files which are known to work on all Debian ports.

A.6.3. dpkg-repack

dpkg-repack creates Debian package file out of a package that has already been installed. If any changes have been made to the package while it was unpacked (e.g., files in /etc were modified), the new package will inherit the changes.

This utility can make it easy to copy packages from one computer to another, or to recreate packages which are installed on your system but no longer available elsewhere, or to save the current state of a package before you upgrade it.

A.6.4. alien

alien converts binary packages between various packaging formats, including Debian, RPM (RedHat), LSB (Linux Standard Base), Solaris, and Slackware packages.

A.6.5. debsums

debsums checks installed packages against their MD5 sums. Note that not all packages have MD5 sums, since they aren't required by Policy.

A.6.6. dpkg-dev-el

dpkg-dev-el is an Emacs lisp package which provides assistance when editing some of the files in the debian directory of your package. For instance, there are handy functions for listing a package's current bugs, and for finalizing the latest entry in a debian/changelog file.

A.6.7. dpkg-depcheck

dpkg-depcheck (from the devscripts package, Section A.6.1, “devscripts) runs a command under strace to determine all the packages that were used by the said command.

For Debian packages, this is useful when you have to compose a Build-Depends line for your new package: running the build process through dpkg-depcheck will provide you with a good first approximation of the build-dependencies. For example:

dpkg-depcheck -b debian/rules build

dpkg-depcheck can also be used to check for run-time dependencies, especially if your package uses exec(2) to run other programs.

For more information please see dpkg-depcheck(1).

A.7. Porting tools

The following tools are helpful for porters and for cross-compilation.

A.7.1. quinn-diff

quinn-diff is used to locate the differences from one architecture to another. For instance, it could tell you which packages need to be ported for architecture Y, based on architecture X.

A.7.2. dpkg-cross

dpkg-cross is a tool for installing libraries and headers for cross-compiling in a way similar to dpkg. Furthermore, the functionality of dpkg-buildpackage and dpkg-shlibdeps is enhanced to support cross-compiling.

A.8. Documentation and information

The following packages provide information for maintainers or help with building documentation.

A.8.1. docbook-xml

docbook-xml provides the DocBook XML DTDs, which are commonly used for Debian documentation (as is the older debiandoc SGML DTD). This manual, for instance, is written in DocBook XML.

The docbook-xsl package provides the XSL files for building and styling the source to various output formats. You will need an XSLT processor, such as xsltproc, to use the XSL stylesheets. Documentation for the stylesheets can be found in the various docbook-xsl-doc-* packages.

To produce PDF from FO, you need an FO processor, such as xmlroff or fop. Another tool to generate PDF from DocBook XML is dblatex.

A.8.2. debiandoc-sgml

debiandoc-sgml provides the DebianDoc SGML DTD, which is commonly used for Debian documentation, but is now deprecated (docbook-xml should be used instead). It also provides scripts for building and styling the source to various output formats.

Documentation for the DTD can be found in the debiandoc-sgml-doc package.

A.8.3. debian-keyring

Contains the public GPG and PGP keys of Debian developers. See Section 3.2.2, “Maintaining your public key” and the package documentation for more information.

A.8.4. debian-maintainers

Contains the public GPG keys of Debian Maintainers. See http://wiki.debian.org/DebianMaintainer for more information.

A.8.5. debview

debview provides an Emacs mode for viewing Debian binary packages. This lets you examine a package without unpacking it.