Chapter 5. Grundlagen

Although a Debian package can be made by writing a debian/rules script without using the debhelper package, it is impractical to do so. There are too many modern “Policy” required features to be addressed, such as application of the proper file permissions, use of the proper architecture dependent library installation path, insertion of the installation hook scripts, generation of the debug symbol package, generation of package dependency information, generation of the package information files, application of the proper timestamp for reproducible build, etc.

Debhelper package provides a set of useful scripts in order to simplify Debian’s packaging workflow and reduce the burden of package maintainers. When properly used, they will help packagers handle and implement “Policy” required features automatically.

The modern Debian packaging workflow can be organized into a simple modular workflow by:

You should almost always use debhelper as your package’s build dependency. This document also assumes that you are using a fairly contemporary version of debhelper to handle packaging works in the following contents.

The dh command from the debhelper package with help from its associated packages functions as the wrapper to the typical upstream build systems and offers us uniform access to them by supporting all the Debian policy stipulated targets of the debian/rules file.

	Note
	For debhelper “compat >= 9”, the dh command exports compiler flags (CFLAGS, CXXFLAGS, FFLAGS, CPPFLAGS and LDFLAGS) with values as returned by dpkg-buildflags if they are not set previously. (The dh command calls set_buildflags defined in the Debian::Debhelper::Dh_Lib module.)

Flexible customization of the debian/rules script is realized by adding appropriate override_dh_* targets and their rules.

Whenever some special operation is required for a certain dh_foo command invoked by the dh command, any automatic execution of it can be overridden by adding the makefile target override_dh_foo in the debian/rules file.

The build process may be customized via the upstream provided interface such as arguments to the standard source build system commands, such as:

If this is the case, you should add the override_dh_auto_build target and executing the “dh_auto_build -- arguments” command. This ensures passing arguments to the such build system after the default parameters that dh_auto_build usually passes.

	Tip
	Please try not to execute the above build system commands directly if they are supported by the dh_auto_build command.

Some variable definitions useful for customizing debian/rules can be found in files under /usr/share/dpkg/. Notably:

If you wish to use some of these useful variables in debian/rules, copy relevant code to debian/rules or write a simpler alternative in it. Please keep debian/rules simple.

Beispielsweise können Sie eine Zusatzoption zu CONFIGURE_FLAGS für die Zielarchitektur linux-any durch Hinzufügen von folgendem zur debian/rules hinzufügen:

DEB_HOST_ARCH_OS ?= $(shell dpkg-architecture -qDEB_HOST_ARCH_OS)
 ...
ifeq ($(DEB_HOST_ARCH_OS),linux)
CONFIGURE_FLAGS += --enable-wayland
endif

	Tip
	It was useful to include buildflags.mk in debian/rules to set the build flags such as CPPFLAGS, CFLAGS, LDFLAGS, etc. properly while honoring DEB_CFLAGS_MAINT_APPEND, DEB_BUILD_MAINT_OPTIONS, etc. for the debhelper “compat <= 8”. Now you should use the debhelper “compat >= 9”, should not include buildflags.mk without specific reasons, and should let the dh command set these build flags.

Here are some recommendations to attain a reproducible build result.

For well behaving build systems, the split of a Debian binary package into small ones can be realized as follows.

Bitte prüfen Sie die Beispiele in dieser Anleitung:

The “dpkg-source -x” command unpacks the Debian source package.

It normally applies the patches in the debian/patches/ directory to the source tree and records the patch state in the .pc/ directory.

The quilt command (or its wrapped dquilt command) was needed to manage the -p1 patches in the debian/patches/ directory before the --commit feature was added to the dpkg-source command in 1.16.1.

The patches should apply cleanly when using the dpkg-source command. Thus you can’t just copy the patches to the new packaging of the new upstream release if there are patch offsets, etc.

The problem of extraneous contents can be fixed by removing such files in the “debian/rules clean” target. This is also useful for auto-generated files.

	Note
	The “debian/rules clean” target is called before the “dpkg-source --build” command by the dpkg-buildpackage command and the “dpkg-source --build” command ignores removed files.

The problem of extraneous contents can be fixed by restoring the source tree by committing the source tree to the VCS before the first build.

You can restore the source tree before the second package build. For example:

 $ git reset --hard
 $ git clean -dfx
 $ debuild

Dies ist für nichtnative Pakete.

The problem of extraneous diffs can be fixed by ignoring changes made to parts of the source tree by adding the “extend-diff-ignore=…” line in the debian/source/options file.

For excluding the config.sub, config.guess and Makefile files:

# Don't store changes on autogenerated files
extend-diff-ignore = "(^|/)(config\.sub|config\.guess|Makefile)$"

	Note
	This approach always works, even when you can’t remove the file. So it saves you having to make a backup of the unmodified file just to be able to restore it before the next build.

	Tip
	If the debian/source/local-options file is used instead, you can hide this setting from the generated source package. This may be useful when the local non-standard VCS files interfere with your packaging.

Dies ist für native Pakete.

You can exclude some files in the source tree from the generated tarball by tweaking the file glob by adding the “tar-ignore=…” lines in the debian/source/options or debian/source/local-options files.

Note

If, for example, the source package of a native package needs files with the file extension .o as a part of the test data, the setting in Section 3.5, “Devscripts” is too aggressive. You can work around this problem by dropping the -I option for DEBUILD_DPKG_BUILDPACKAGE_OPTS in Section 3.5, “Devscripts” while adding the “tar-ignore=…” lines in the debian/source/local-options file for each package.

Autotools (autoconf + automake) has 4 steps.

The upstream maintainer usually performs step 1 and builds the upstream tarball for distribution using the “make dist” command. (The generated tarball contains not only the pristine upstream VCS contents but also other generated files.)

The package maintainer needs to take care of steps 2 to 4 at least. This is realized by the “dh $@ --with autotools-dev” command used in the debian/rules file.

The package maintainer may wish to take care all steps 1 to 4. This is realized by the “dh $@ --with autoreconf” command used in the debian/rules file. This rebuilds all auto-generated files to the latest version and provides better support for porting to the newer architectures.

For compat level 10 or newer, the simple “dh $@” command without “--with autoreconf” option can take care all steps 1 to 4, too.

Falls Sie mehr über die Autotools lernen möchten, lesen Sie:

CMake hat 4 Schritte.

Der Tarball der Originalautoren enthält keine automatisch erstellten Dateien und wird durch den Befehl tar nach Schritt 1 erstellt.

Der Paketbetreuer muss sich um die Schritte 2 bis 4 kümmern.

Falls Sie mehr über CMake lernen möchten, lesen Sie bitte:

Meson hat 4 Schritte.

Der Tarball der Originalautoren enthält keine automatisch erstellten Dateien und wird durch den Befehl tar nach Schritt 1 erstellt.

Der Paketbetreuer muss sich um die Schritte 2 bis 4 kümmern.

Falls Sie mehr über Meson lernen möchten, lesen Sie bitte:

Python Distutils hat 3 Schritte.

Die Originalautoren führen normalerweise Schritt 1 durch und bauen den Tarball der Originalautoren mittels des Befehls »python3 setup.py sdist« zum Verteilen.

The package maintainer needs to take care of step 2. This is realized simply by the “dh $@” command used in the debian/rules file.

These days, most upstream maintainers of Python packages use setuptools with wheel. Since setuptools is an extension of distutils, this step 2 works as expected even if setup.py doesn’t explicitly uses distutils.

Falls Sie mehr über Python3 und distutils und setuptools lernen möchten, lesen Sie bitte:

The debugging information is automatically packaged separately as the debug package using the dh_strip command with its default behavior. The name of such a debug package normally has the -dbgsym suffix.

If there were no -dbg packages defined in the debian/control file, no special care is needed for updating the package after the Stretch 9.0 release.

If there were -dbg packages defined in the debian/control file, following care is needed for updating the old package after the Stretch 9.0 release.

The symbols support in dpkg introduced in Debian lenny (5.0, May 2009) helps us to manage the backward ABI compatibility of the library package with the same package name. The DEBIAN/symbols file in the binary package provides the minimal version associated with each symbol.

An oversimplified method for the library packaging is as follows.

For the details, you should read the following primary references.

For Autotools based packages under the debhelper package (compat>=9), this path setting is automatically taken care by the dh_auto_configure command.

For other packages with non-supported build systems, you need to manually adjust the install path as follows.

All files installed simultaneously as the multiarch package to the same file path should have exactly the same file content. You must be careful with differences generated by the data byte order and by the compression algorithm.

Note

The --libexecdir option of the ./configure command specifies the default path to install executable programs run by other programs rather than by users. Its Autotools default is /usr/libexec/ but its Debian non-multi-arch default is /usr/lib/. If such executables are a part of a "Multi-arch: foreign" package, a path such as /usr/lib/ or /usr/lib/packagename may be more desirable than /usr/lib/<triplet>/, which dh_auto_configure uses. The GNU Coding Standards: 7.2.5 Variables for Installation Directories has a description for libexecdir as "The definition of libexecdir is the same for all packages, so you should install your data in a subdirectory thereof. Most packages install their data under $(libexecdir)/package-name/ …". (It is always a good idea to follow GNU unless it conflicts with the Debian policy.)

The shared library files in the default path /usr/lib/ and /usr/lib/<triplet>/ are loaded automatically.

For shared library files in another path, the GCC option -l must be set by the pkg-config command to make them load properly.

GCC includes both /usr/include/ and /usr/include/<triplet>/ by default on the multiarch Debian system.

If the header file is not in those paths, the GCC option -I must be set by the pkg-config command to make "#include <foo.h>" work properly.

The pkg-config program is used to retrieve information about installed libraries in the system. It stores its configuration parameters in the *.pc file and is used for setting the -I and -l options for GCC.