If you're looking to get started at packaging free software for
Debian, you should start with the excellent
New Maintainers' Guide or
the
Introduction to Debian Packaging
on the Debian wiki.
Once you know the basics, or if you prefer to learn by example, you may be
interested in the full walkthrough which follows. We will look at the
contents of three simple packages.
node-libravatar
This package is a
node.js library for the
Libravatar service.
Version 2.0.0-3
of that package contains the following files in its debian/ directory:
changelog
compat
control
copyright
docs
node-libravatar.install
rules
source/format
watch
debian/control
This is probably the most important file since it contains the bulk of the
metadata about this package.
Maintainer is a required field listing the maintainer of that package,
which can be a person or a team. It only contains a single value though, any
co-maintainers will be listed under the optional Uploaders field.
Build-Depends lists the packages which are needed to build the
package (e.g. a compiler), as opposed to those which are needed to
install the binary package (e.g. a library it uses).
Standards-Version refers to the version of the
Debian Policy that this package
complies with.
The Homepage field refers to the upstream homepage, whereas the
Vcs-* fields point to the repository where the packaging is stored. If
you take a look at the
node-libravatar packaging repository
you will see that it contains three branches:
upstream is the source as it was in the tarball downloaded from
upstream.
master is the upstream branch along with all of the Debian
customizations.
pristine-tar is unrelated to the other two branches and is used by the
pristine-tar tool
to reconstitute the original upstream tarball as needed.
After these fields comes a new section which starts with a Package
field. This is the definition of a binary package, not to be confused
with the Source field at the top of this file, which refers to the name of
the source package. In this particular example, they are both the same
and there is only one of each, however this is not always the case, as we'll
see later.
Inside that binary package definition, lives the Architecture field which
is normally one of these two:
all for a binary package that will work on all architectures but only
needs to be built once
any for a binary package that will work everywhere but that will need to
be built separately for each architecture
Finally, the last field worth pointing out is the Depends field which
lists all of the runtime dependencies that the binary package has. This is
what will be pulled in by apt-get when you apt-get install
node-libravatar. The two variables will be substituted later by debhelper.
debian/changelog
This may seem at first like a mundane file, but it is very important since
it is the canonical source of the package version (2.0.0-3 in this
case). This is the only place where you need to bump the package version
when uploading a new package to the Debian archive.
The first line also includes the
distribution
where the package will be uploaded. It is usually one of these values:
unstable for the vast majority of uploads
stable for uploads that have been approved by the release maintainers
and fix serious bugs in the stable version of Debian
stable-security for security fixes to the stable version of Debian that
cannot wait until the next stable point release and have been
approved by the security team
Packages uploaded to unstable will migrate automatically to testing
provided that a few conditions are met (e.g. no release-critical bugs were
introduced). The length of time before that migration is influenced by the
urgency field (low, medium or high) in the changelog entry.
Another thing worth noting is that the first upload normally needs to close
an ITP (Intent to Package) bug.
debian/rules
As can be gathered from the first two lines of this file, this is a
Makefile. This
is what controls how the package is built.
There's not much to see and that's because most of its content is
automatically added by debhelper. So
let's look at it in action by building the package:
and then looking at parts of the build log (../node-libravatar_2.0.0-3_amd64.build):
One of the first things we see is the debian/rules file being run with the
clean target. To find out what that does, have a look at the
dh_auto_clean
which states that it will attempt to delete build residues and run something
like make clean using the upstream Makefile.
Next we see the build target being invoked and looking at
dh_auto_configure
we see that this will essentially run ./configure and its
equivalents.
The
dh_auto_build
helper script then takes care of running make (or equivalent) on the
upstream code.
This should be familiar to anybody who has ever built a piece of free
software from scratch and has encountered the usual method for building
from source:
Finally, we get to actually build the .deb:
Here we see a number of helpers, including
dh_auto_install
which takes care of running make install.
Going back to the debian/rules, we notice that there is manually defined
target at the bottom of the file:
which essentially disables
dh_auto_test
by replacing it with an empty set of commands.
The reason for this becomes clear when we take a look at the test target
of the upstream Makefile and the
dependencies
it has: tap, a node.js library that is
not yet available in Debian.
In other words, we can't run the test suite on the build machines so we need
to disable it here.
debian/compat
This file simply specifies the version of debhelper that is required by the
various helpers used in debian/rules. Version 9 is the latest at the moment.
debian/copyright
This machine-readable file lists all of the different licenses encountered in this
package.
It requires that the maintainer audits the upstream code for any copyright
statements that might be present in addition to the license of the package
as a whole.
debian/docs
This file contains a list of upstream files that will be copied into the
/usr/share/doc/node-libravatar/ directory by dh_installdocs.
debian/node-libravatar.install
The install file is used by
dh_install
to supplement the work done by dh_auto_install which, as we have seen
earlier, essentially just runs make install on the upstream Makefile.
Looking at that
upstream Makefile,
it becomes clear that the files will need to be installed manually by the
Debian package since that Makefile doesn't have an install target.
debian/watch
This is the file that allows Debian tools like the
Package Tracking System
to automatically detect that a new upstream version is available.
What it does is simply visit the
upstream page which contains all of the
release tarballs and look
for links which have an
href
matching the above regular expression.
Running uscan --report --verbose will show us all of the tarballs that can
be automatically discovered using this watch file:
pylibravatar
This second package is the
equivalent Python library for the Libravatar service.
Version 1.6-2
of that package contains similar files in its debian/ directory, but let's
look at two in particular:
control
upstream/signing-key.asc
debian/control
Here is an example of a source package (pylibravatar) which builds two
separate binary packages: python-libravatar and python3-libravatar.
This highlights the fact that a given upstream source can be split into
several binary packages in the archive when it makes sense. In this case,
there is no point in Python 2 applications pulling in the Python 3 files, so
the two separate packages make sense.
Another common example is the use of a -doc package to separate the
documentation from the rest of a package so that it doesn't need to be
installed on production servers for example.
debian/upstream/signing-key.asc
This is simply the
OpenPGP key
that the upstream developer uses to sign release tarballs.
Since PGP signatures are available on the upstream
download page, it's possible
to instruct
uscan
to check signatures before downloading tarballs.
The way to do that is to use the pgpsigurlmange option in debian/watch:
which is simply a regular expression replacement string which takes the
tarball URL and converts it to the URL of the matching PGP signature.
fcheck
The last package we will look at
is a file integrity checker. It essentially goes through all of the files in
/usr/bin/ and /usr/lib/ and stores a hash of them in its database. When
one of these files changes, you get an email.
In particular, we will look at the following files in the debian/ directory of
version 2.7.59-18:
dirs
fcheck.cron.d
fcheck.postrm
fcheck.postinst
patches/
README.Debian
rules
source/format
debian/patches
This directory contains ten patches as well as a file called series which
lists the patches that should be applied to the upstream source and in which
order. Should you need to temporarily disable a patch, simply remove it from
this file and it will no longer be applied at build time.
Let's have a look at patches/04_cfg_sha256.patch:
This is a very simple patch which changes the default configuration of
fcheck to promote the use of a stronger hash function. At the top of the
file is a bunch of metadata in the
DEP-3 format.
Why does this package contain so many customizations to the upstream code
when Debian's policy is to push fixes upstream and work towards reduce the
delta between upstream and Debian's code? The answer can be found in
debian/control:
This package no longer has an upstream maintainer and its original source is
gone. In other words, the Debian package is where all of the new bug fixes
get done.
debian/source/format
This file contains what is called the source package format. What it
basically says is that the patches found in debian/patches/ will be
applied to the upstream source using the
quilt tool at build time.
debian/fcheck.postrm
This script is one of the many possible
maintainer scripts that a
package can provide if needed.
This particular one, as the name suggests, will be run after the package is
removed (apt-get remove fcheck) or purged (apt-get remove --purge
fcheck). Looking at the case statement above, it doesn't do anything extra in the
remove case, but it deletes a few files and directories when called with
the purge argument.
debian/README.Debian
This optional README file contains Debian-specific instructions that might
be useful to users. It supplements the upstream README which is
often more generic and cannot assume a particular system configuration.
debian/rules
This is an example of a old-style debian/rules file which you still
encounter in packages which haven't yet upgraded to the latest version of
debhelper 9, as can be shown by the contents of debian/compat:
It does essentially the same thing that what we've seen in the build log,
but in a more verbose way.
debian/dirs
This file contains a list of directories that
dh_installdirs
will create in the build directory.
The reason why these directories need to be created is that files are copied
into these directories
in the install target of the debian/rules file.
Note that this is different from directories which are created at the time
of installation of the package. In that case, the directory
(e.g. /var/log/fcheck/) must be
created in the postinst script
and removed in the postrm script.
debian/fcheck.cron.d
This file is the cronjob which drives the checks performed by this
package. It will be copied to /etc/cron.d/fcheck by dh_installcron.