Debian Packaging

Documentation and Guides

• Developer Manuals
• https://wiki.debian.org/PackageManagementTools
• LCFG Buildtools Debian support - BuildToolsDebian

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