Kapitel 9. More on packaging

# Kapitel 9. More on packaging

Let’s explore more fundamentals of Debian packaging.

## 9.1. Package customization

All customization data for the Debian source package resides in the debian/ directory as presented in „Abschnitt 5.7, „Schritt 3: Anpassung der Vorlagendateien““:

- The Debian package build system can be customized through the debian/rules file (see „Abschnitt 9.2, „Customized debian/rules““).
- The Debian package installation path etc. can be customized through the addition of configuration files such as package.install and package.docs in the debian/ directory for the dh_* commands from the debhelper package (see „Abschnitt 6.14, „Other debian/* files““).

When these are not sufficient to make a good Debian package, -p1 patches of debian/patches/* files are deployed to modify the upstream source. These are applied in the sequence defined in the debian/patches/series file before building the package as presented in „Abschnitt 5.9, „Step 3 (alternatives): Modification to the upstream source““.

You should address the root cause of the Debian packaging problem in the least invasive way possible. This approach will make the generated package more robust for future upgrades.

| Anmerkung
If the patch addressing the root cause is useful to the upstream project, send it to the upstream maintainer.

## 9.2. Customized debian/rules

Flexible customization of the Abschnitt 6.5, „debian/rules file“ is achieved by adding appropriate override_dh_* targets and their rules.

When a special operation is required for a certain dh_foo command invoked by the dh command, its automatic execution 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:

- configure,
- Makefile,
- „python -m build“, or
- Build.PL.

In this case, you should add the override_dh_auto_build target with „dh_auto_build -- arguments“. This ensures that arguments are passed to the build system after the default parameters that dh_auto_build usually passes.

| Tipp
Avoid executing bare build system commands directly if they are supported by the dh_auto_build command.

Siehe:

- „Abschnitt 5.7, „Schritt 3: Anpassung der Vorlagendateien““ for the basic example.
- „Abschnitt 10.3, „Note on build system““ to be reminded of the challenge involving the underlying build system.
- „Abschnitt 10.10, „Multiarch““ for multiarch customization.
- „Abschnitt 10.6, „Compiler hardening““ for hardening customization.

## 9.3. Variables for debian/rules

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

pkg-info.mk
  Set DEB_SOURCE, DEB_VERSION, DEB_VERSION_EPOCH_UPSTREAM, DEB_VERSION_UPSTREAM_REVISION, DEB_VERSION_UPSTREAM, and DEB_DISTRIBUTION variables obtained from dpkg-parsechangelog(1). (useful for backport support etc..)
vendor.mk
  Set DEB_VENDOR and DEB_PARENT_VENDOR variables; and dpkg_vendor_derives_from macro obtained from dpkg-vendor(1). (useful for vendor support (Debian, Ubuntu, …​).)
architecture.mk
  Set DEB_HOST_* and DEB_BUILD_* variables obtained from dpkg-architecture(1).
buildflags.mk
  Set CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS, FCFLAGS, and LDFLAGS build flags obtained from dpkg-buildflags(1).

For example, you can add an extra option to CONFIGURE_FLAGS for linux-any target architectures by adding the following to debian/rules:

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

Siehe „Abschnitt 10.10, „Multiarch““, dpkg-architecture(1) und dpkg-buildflags(1).

## 9.4. New upstream release

When a new upstream release tarball debhello-newvwesion.tar.xz is released, the Debian source package can be updated by invoking commands in the old source tree as:

    [debhello-0.0] $ uscan
     ... debhello-newversion.tar.xz downloaded
    [debhello-0.0] $ uupdate -v newversion ../debhello-newversion.tar.xz

- The debian/watch file in the old source tree must be a valid one.
- This make symlink ../debhello_newvwesion.orig.tar.xz pointing to ../debhello-newvwesion.tar.xz.
- Files are extracted from ../debhello-newvwesion.tar.xz to ../debhello-newversion/
- Files are copied from ../debhello-oldversion/debian/ to ../debhello-newvesion/debian/ .

After the above, you should refresh debian/patches/* files (see „Abschnitt 9.5, „Manage patch queue with dquilt““) and update debian/changelog with the dch(1) command.

When „debian uupdate“ is specified at the end of line in the debian/watch file, uscan automatically executes uupdate(1) after downloading the tarball.

## 9.5. Manage patch queue with dquilt

You can add, drop, and refresh debian/patches/* files with dquilt to manage patch queue.

- Add a new patch debian/patches/bugname.patch recording the upstream source modification on the file buggy_file as:

      [debhello-0.0] $ dquilt push -a
      [debhello-0.0] $ dquilt new bugname.patch
      [debhello-0.0] $ dquilt add buggy_file
      [debhello-0.0] $ vim buggy_file
        ...
      [debhello-0.0] $ dquilt refresh
      [debhello-0.0] $ dquilt header -e
      [debhello-0.0] $ dquilt pop -a

- Drop (== disable) an existing patch

  - Comment out pertinent line in debian/patches/series
  - Erase the patch itself (optional)

- Refresh debian/patches/* files to make „dpkg-source -b“ work as expected after updating a Debian package to the new upstream release.

      [debhello-0.0] $ uscan; uupdate  # updating to the new upstream release
      [debhello-0.0] $ while dquilt push; do dquilt refresh ; done
      [debhello-0.0] $ dquilt pop -a

  - If conflicts are encountered with „dquilt push“ in the above, resolve them and run „dquilt refresh“ manually for each of them.

## 9.6. Build commands

Here is a recap of popular low level package build commands. There are many ways to do the same thing.

- dpkg-buildpackage = core of package building tool
- debuild = dpkg-buildpackage + lintian (build under the sanitized environment variables)
- schroot = core of the Debian chroot environment tool
- sbuild = dpkg-buildpackage on custom schroot (build in the chroot)

## 9.7. Note on sbuild

The sbuild(1) command is a wrapper script of dpkg-buildpackage which builds Debian binary packages in a chroot environment managed by the schroot(1) command. For example, building for Debian unstable suite can be done as:

    [debhello-0.0] $ sudo sbuild -d unstable

In schroot(1) terminology, this builds a Debian package in a clean ephemeral chroot „chroot:unstable-amd64-sbuild“ started as a copy of the clean minimal persistent chroot „source:unstable-amd64-sbuild“.

This build environment was set up as described in „Abschnitt 4.7, „sbuild setup““ with „sbuild-debian-developer-setup -s unstable“ which essentially did the following:

    [~] $ sudo mkdir -p /srv/chroot/dist-amd64-sbuild
    [~] $ sudo sbuild-createchroot unstable /srv/chroot/unstable-amd64-sbuild http://deb.debian.org/debian
    [~] $ sudo usermod -a -G sbuild <your_user_name>
    [~] $ sudo shutdown -r now
     ... reboot

The schroot(1) configuration for unstable-amd64-sbuild was generated at /etc/schroot/chroot.d/unstable-amd64-sbuild.$suffix :

    [unstable-amd64-sbuild]
    description=Debian sid/amd64 autobuilder
    groups=root,sbuild
    root-groups=root,sbuild
    profile=sbuild
    type=directory
    directory=/srv/chroot/unstable-amd64-sbuild
    union-type=overlay

Hier:

- The profile defined in the /etc/schroot/sbuild/ directory is used to setup the chroot environment.
- /srv/chroot/unstable-amd64-sbuild directory holds the chroot filesystem.
- /etc/sbuild/unstable-amd64-sbuild is symlinked to /srv/chroot/unstable-amd64-sbuild .

You can update this source chroot „source:unstable-amd64-sbuild“ by:

    [~] $ sudo sbuild-update -udcar unstable

You can log into this source chroot „source:unstable-amd64-sbuild“ by:

    [~] $ sudo sbuild-shell unstable

| Tipp
If your source chroot filesystem is missing packages such as libeatmydata1, ccache, and lintian for your needs, you may want to install these by logging into it.

## 9.8. Special build cases

The orig.tar.xz file may need to be uploaded for a Debian revision other than 0 or 1 under some exceptional cases (e.g., for a security upload).

When an essential package becomes a non-essential one (e.g., adduser), you need to remove it manually from the existing chroot environment for its use by piuparts.

## 9.9. Upload orig.tar.xz

When you first upload the package to the archive, you need to include the original orig.tar.xz source, too.

If the Debian revision number of the package is either 1 or 0, this is the default. Otherwise, you must provide the dpkg-buildpackage option -sa to the dpkg-buildpackage command.

- dpkg-buildpackage -sa
- debuild -sa
- sbuild --debbuildopts=-sa
- gbp buildpackage -sa

| Tipp
On the other hand, the -sd option will force the exclusion of the original orig.tar.xz source.

| Tipp
Security uploads require including the orig.tar.xz file.

## 9.10. Skipped uploads

If you created multiple entries in the debian/changelog while skipping uploads, you must create a proper *_.changes file which includes all changes since the last upload. This can be done by specifying the dpkg-buildpackage option -v with the last uploaded version, e.g., 1.2.

- dpkg-buildpackage -v 1.2
- debuild -v 1.2
- sbuild --debbuildopts=-v 1.2
- gbp buildpackage -v 1.2

## 9.11. Bug reports

The reportbug(1) command used for the bug report of binarypackage can be customized by the files in usr/share/bug/binarypackage/.

The dh_bugfiles command installs these files from the template files in the debian/ directory.

- debian/binarypackage.bug-control → usr/share/bug/binarypackage/control

  - This file contains some directions such as redirecting the bug report to another package.

- debian/binarypackage.bug-presubj → usr/share/bug/binarypackage/presubj

  - This file is displayed to the user by the reportbug command.

- debian/binarypackage.bug-script → usr/share/bug/binarypackage or usr/share/bug/binarypackage/script

  - The reportbug command runs this script to generate a template file for the bug report.

See dh_bugfiles(1) and „reportbug’s Features for Developers (README.developers)“

| Tipp
If you always remind the bug reporter of something or ask them about their situation, use these files to automate it.

Kapitel 8. Sanitization of the source |  | Kapitel 10. Advanced packaging