Debian Packaging
Documentation and Guides
Standard Package Files
When the
gendeb
command is used to generate the debian packaging metadata the following files will be generated for every project:
- debian/compat - debhelper compatibility level (currently 11)
- debian/control - Source and binary packages information
- debian/copyright - Copyright statement for the project (defaults to GPLv2)
- debian/docs - List of extra documentation files which are not installed as part of the build/install process (e.g. ChangeLog and README)
- debian/rules - The package build script, this is usually quite minimal
- debian/source/format - Source package format (defaults to
3.0 (quilt)
), it's unlikely to need changing
If the project looks like an LCFG component then the following files will also be generated:
- debian/lcfg-file.service - a systemd service file for the component (for when the systemd component is not available)
- debian/postinst - post-install script, calls component
configure
method
- debian/postrm - post-removal script, removes the logrotate file to avoid warnings
- debian/prerm - attempts to stop the component on removal
debian/control
This contains the metadata for the source package and all the binary packages which are to be generated. Each package section is separated by an empty line. Note that multi-line values may be used as long as subsequent lines are indented with whitespace. For example:
Source: lcfg-example
Section: admin
Priority: optional
Maintainer: Stephen Quinney <squinney@inf.ed.ac.uk>
Build-Depends: debhelper (>= 11), cmake, perl (>= 5.16.0)
Standards-Version: 4.1.3
Homepage: https://www.lcfg.org/
Vcs-Svn: https://svn.lcfg.org/svn/source/trunk/lcfg-example
Vcs-Browser: https://svn.lcfg.org/viewvc/source/trunk/lcfg-example
Package: lcfg-example
Architecture: all
Depends: ${misc:Depends}, ${perl:Depends},
lcfg-om,
lcfg-ngeneric
Description: Example LCFG component
An Example LCFG component
The source package information must always come first, after that there should be a Package section for each binary package that will be generated.
The main parts that are likely to need modifying are the
Build-Depends
and
Depends
. The automatic gathering of dependencies is not as extensive as with RPMs, in particular all Perl or Python module dependencies have to be worked out manually. The package repository can be queried using the
apt-file
tool or, for Perl modules, the
dh-make-perl
tool, e.g.
% dh-make-perl locate LWP::UserAgent
== dh-make-perl 0.104 ==
Parsing Contents files:
contrib_Contents-amd64.lz4
main_Contents-amd64.lz4
non-free_Contents-amd64.lz4
LWP::UserAgent is in libwww-perl package
One notable difference between Debian and Redhat is that on Debian you can only depend upon the names of packages, it's not possible to depend on file paths, e.g.
/usr/bin/foo
or perl module names, e.g.
perl(Foo::Bar)
debian/changelog
This file is
not created by the
gendeb
command. Once the
debian
sub-directory exists for a project the
debian/changelog
file will be managed by the LCFG buildtools. When a version is tagged (using
major
,
minor
or
micro) it will be updated accordingly, similarly when a =dev
command (e.g.
devpack
,
devrpm
,
devdeb
) is used an entry will be added to the exported copy (your svn working copy will be untouched). Note that this changelog is for the Debian package and does not contain a log of the source changes, those are stored in the separate
ChangeLog
file which will usually be installed as part of the package.
To ensure a valid name and email address are inserted into the
debian/changelog
set
DEBFULLNAME
and
DEBEMAIL
environment variables, e.g.
export DEBFULLNAME="Joe Bloggs"
export DEBEMAIL="joe.bloggs@example.org
Otherwise your username and local domain will be used.
debian/rules
This is a Makefile. The generation of packages can be done in various ways, we've chosen to use
debhelper
which means that in it's most basic state this file can be mystifyingly empty. That's because it will usually successfully auto-detect what is required, it can easily handle CMake and Perl module building without any changes. When first generated the file will look like this:
#!/usr/bin/make -f
%:
dh $@
# This is for CMake
override_dh_auto_configure:
dh_auto_configure -- -DPERL_INSTALLDIRS:STRING=vendor
There is an override for the configure stage to set the correct install location for Perl modules which is required for our LCFG CMake build system.
For LCFG components there will be an extra section like this which tweaks how the systemd service file is installed.
override_dh_installsystemd:
dh_installsystemd --no-enable --no-start --no-restart-on-upgrade
Pretty much any standard debhelper command can be replaced or extended in this way by using an
override_<command name>
target.
debian/docs
Sometimes a project supplies extra documentation files which are not installed as part of the standard build/install process. To get those files included in the package you need to add them to the
debian/docs
file, that will typically already exist and, at least, include the
ChangeLog
.
debian/manpages
Most manpages will be generated and installed as part of the build process (i.e. using CMake) but if you have extras that need to be generated using a tool like
pod2man
then this can be be done by extending the
dh_installman
target like this:
override_dh_installman:
pod2man --section=8 sbin/lcfgmkdir lcfgmkdir.8
dh_installman
The pod2man tool is provided as part of the perl package so that must be in the
Build-Depends
list in the
debian/control
file.
You then also need to add a
debian/manpages
file (remember to
svn add
it) which lists the files to be included:
lcfgmkdir.8
--
squinney - 2019-02-05