1. Overview of Debian Maintainer Tools
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 that 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.
1.1. Core tools
The following tools are pretty much required for any maintainer.
1.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.
1.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 that require
interactive configuration; see Configuration management with debconf. debconf
is not currently required by Debian Policy, but that may change in the
future.
1.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,
dpkg-buildpackage
will use it automatically.
1.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.
1.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 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 https://lintian.debian.org/. These reports contain
the latest lintian
output for the whole development distribution
(unstable
).
1.2.2. lintian-brush
lintian-brush
contains a set of scripts that can automatically
fix more than 80 common lintian issues in Debian packages.
It comes with a wrapper script that invokes the scripts, updates the changelog (if desired) and commits each change to version control.
1.2.3. piuparts
piuparts
is the .deb
package installation, upgrading, and removal
testing tool.
piuparts
tests that .deb packages
handle installation, upgrading,
and removal correctly. It does this by creating a minimal Debian
installation in a chroot, and installing, upgrading, and removing packages
in that environment, and comparing the state of the directory tree before
and after. piuparts
reports any files that have been added, removed,
or modified during this process.
piuparts
is meant as a quality assurance tool for people who create
.deb
packages to test them before they upload them to the Debian
archive.
1.2.4. debdiff
debdiff
(from the devscripts
package, 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.
1.2.5. diffoscope
diffoscope
provides in-depth comparison of files, archives, and directories.
diffoscope
will try to get to the bottom of what makes files or directories
different. It will recursively unpack archives of many kinds and transform
various binary formats into more human readable form to compare them.
Originally developed to compare two .deb
files or two changes
files
nowadays it can compare two tarballs, ISO images, or PDF just as easily and
supports a huge variety of filetypes.
The differences can be shown in a text or HTML report or as JSON output.
1.2.6. duck
duck
, the Debian Url ChecKer, processes several fields in the
debian/control
, debian/upstream
, debian/copyright
,
debian/patches/*
and systemd.unit
files and checks if URLs,
VCS links and email address domains found therein are valid.
1.2.7. adequate
adequate
checks packages installed on the system and reports bugs
and policy violations.
The following checks are currently implemented:
broken symlinks
missing copyright file
obsolete conffiles
Python modules not byte-compiled
/bin
and/sbin
binaries requiring/usr/lib
librariesmissing libraries, undefined symbols, symbol size mismatches
license conflicts
program name collisions
missing alternatives
missing
binfmt
interpreters and detectorsmissing
pkg-config
dependencies
1.2.8. i18nspector
i18nspector
is a tool for checking translation templates (POT), message
catalogues (PO) and compiled message catalogues (MO) files for common problems.
1.2.9. cme
cme
is a tool from the libconfig-model-dpkg-perl
package is an editor
for dpkg source files with validation. Check the package description to see
what it can do.
1.2.10. licensecheck
licensecheck
attempts to determine the license that applies to each
file passed to it, by searching the start of the file for text belonging
to various licenses.
1.2.11. blhc
blhc
is a tool which checks build logs for missing hardening flags.
1.3. Helpers for debian/rules
Package building tools make the process of writing debian/rules
files easier. See Helper scripts for more information about
why these might or might not be desired.
1.3.1. debhelper
debhelper
is a collection of programs that 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-
.
When choosing a debhelper
compatibility level for your package, you
should choose the highest compatibility level that is supported in the
most recent stable release. Only use a higher compatibility level if you
need specific features that are provided by that compatibility level
that are not available in earlier levels.
In the past the compatibility level was defined in debian/compat
,
however nowadays it is much better to not use that but rather to use a
versioned build-dependency like debhelper-compat (=12)
.
1.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.
1.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.
1.4. Package builders
The following packages help with the package building process, general
driving of dpkg-buildpackage
, as well as handling supporting tasks.
1.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.
1.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.
1.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 a COW filesystem on any standard Linux filesystem.
1.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 wanna-build for more
information, and https://buildd.debian.org/ to see the system in
action.
1.5. Package uploaders
The following packages help automate or simplify the process of uploading packages into the official archive.
1.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 optionally send
mail about the upload of a package. It supports various kinds of hooks to
extend its functionality, and can be configured for new upload locations
or methods, although by default it provides various hooks performing checks
and comes configured with all Debian upload locations.
1.5.2. dput
The dput
package and script do much the same thing as dupload
,
but in a different way. Out of the box it supports to run dinstall
in dry-run mode after the upload.
1.5.3. dcut
The dcut
script (part of the package dput
, dput) helps
in removing files from the ftp upload directory.
1.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
.
1.6.1. devscripts
devscripts
is a package containing wrappers and tools that are very
helpful for maintaining your Debian packages. Example scripts include
debchange
(or its alias, dch
), which manipulates 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 (see https://wiki.debian.org/debian/watch for more info on that).
suspicious-source
outputs a list of files which are not common source
files.
See the devscripts 1 manual page for a complete list of available scripts.
1.6.2. reportbug
reportbug
is a tool designed to make the reporting of bugs in Debian
and derived distributions relatively painless. Its features include:
Integration with mutt and mh/nmh mail readers.
Access to outstanding bug reports to make it easier to identify whether problems have already been reported.
Automatic checking for newer versions of packages.
reportbug
is designed to be used on systems with an installed mail
transport agent; however, you can edit the configuration file and send
reports using any available mail server.
This package also includes the querybts
script for browsing the
Debian bug tracking system.
1.6.3. autotools-dev
autotools-dev
contains best practices for people who maintain
packages that use autoconf
and/or automake
. Also contains
canonical config.sub
and config.guess
files, which are known to
work on all Debian ports.
1.6.4. dpkg-repack
dpkg-repack
creates a 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 that are installed on your system but no longer available elsewhere, or to save the current state of a package before you upgrade it.
1.6.5. alien
alien
converts binary packages between various packaging formats,
including Debian, RPM (RedHat), LSB (Linux Standard Base), Solaris, and
Slackware packages.
1.6.6. dpkg-dev-el
dpkg-dev-el
is an Emacs lisp package that 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.
1.6.7. dpkg-depcheck
dpkg-depcheck
(from the devscripts
package, 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.
1.7. Porting tools
The following tools are helpful for porters and for cross-compilation.
1.7.1. 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.
1.8. Documentation and information
The following packages provide information for maintainers or help with building documentation.
1.8.1. debian-policy
The debian-policy
package contains the Debian Policy Manual
and related documents, which are:
Debian Policy Manual
Filesystem Hierarchy Standard (FHS)
Debian Menu sub-policy
Debian Perl sub-policy
Debian configuration management specification
Machine-readable debian/copyright specification
Autopkgtest - automatic as-installed package testing
Authoritative list of virtual package names
Policy checklist for upgrading your packages
The Debian Policy Manual the policy relating to packages and details of
the packaging mechanism. It covers everything from required gcc
options to the way the maintainer scripts (postinst
etc.) work,
package sections and priorities, etc.
Also useful is the file
/usr/share/doc/debian-policy/upgrading-checklist.txt.gz
,
which lists changes between versions of policy.
1.8.2. doc-debian
doc-debian
contains lots of useful Debian-specific documentation:
Debian Linux Manifesto
Constitution for the Debian Project
Debian Social Contract
Debian Free Software Guidelines
Debian Bug Tracking System documentation
Introduction to the Debian mailing lists
1.8.3. developers-reference
The developers-reference
package contains the document you are
reading right now, the Debian Developer's Reference, a set of
guidelines and best practices which has been established by and for
the community of Debian developers.
1.8.4. maint-guide
The maint-guide
package contains the Debian New Maintainers' Guide.
This document tries to describe the building of a Debian package to ordinary Debian users and prospective developers. It uses fairly non-technical language, and it's well covered with working examples.
1.8.5. packaging-tutorial
This tutorial is an introduction to Debian packaging. It teaches prospective developers how to modify existing packages, how to create their own packages, and how to interact with the Debian community.
In addition to the main tutorial, it includes three practical sessions
on modifying the grep
package, and packaging the gnujump
game
and a Java library.
1.8.6. how-can-i-help
how-can-i-help
shows opportunities for contributing to Debian.
how-can-i-help
hooks into APT
to list opportunities for contributions to
Debian (orphaned packages, bugs tagged 'newcomer') for packages installed
locally, after each APT
invocation. It can also be invoked directly, and
then lists all opportunities for contribution (not just the new ones).
1.8.7. docbook-xml
docbook-xml
provides the DocBook XML DTDs, which are commonly used
for Debian documentation (as is the older debiandoc SGML DTD).
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
.
1.8.8. debiandoc-sgml
debiandoc-sgml
provides the DebianDoc SGML DTD, which has been
commonly used for Debian documentation, but is now deprecated
(docbook-xml
or python3-sphinx
should be used instead).
1.8.9. debian-keyring
Contains the public OpenPGP keys of Debian Developers and Maintainers. See Maintaining your public key and the package documentation for more information.
1.8.10. debian-el
debian-el
provides an Emacs mode for viewing Debian binary packages.
This lets you examine a package without unpacking it.