// vim:set filetype=asciidoc:
[[more-packaging]]
== More on packaging

Let's describe more basics on Debian packaging.

[[custom]]
=== Package customization

All customization data for the Debian source package resides in the *debian/* directory as presented in "`<<step-maintainer>>`":

* The Debian package build system can be customized through the *debian/rules* file (see "`<<rules-custom>>`").
* 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 "`<<debianconf>>`").

When these are not sufficient to make a good Debian package, *-p1* patches of <<patches>> 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 "`<<alt-patch>>`".

You should address the root cause of the Debian packaging problem by the least invasive way.  The generated package shall be more robust for future upgrades in this way.

NOTE: Send the patch addressing the root cause to the upstream maintainer if it is useful to the upstream.

[[rules-custom]]
=== Customized *debian/rules*

Flexible customization of the <<rules>> 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:

* **configure**,
* **Makefile**,
* "`**python -m build**`", or
* **Build.PL**.

If this is the case, you should add the *override_dh_auto_build* target with "`**dh_auto_build --** __arguments__`".  This ensures passing __arguments__ to the build system after the default parameters that *dh_auto_build* usually passes.

TIP: Please try not to execute the bare build system commands directly if they are supported by the *dh_auto_build* command.

See:

* "`<<step-maintainer>>`" for the basic example.
* "`<<build-system>>`" to be reminded of the challenge involving the underlying build system.
* "`<<multiarch>>`" for multiarch customization.
* "`<<harden>>`" for hardening customization.

[[rules-variables]]
=== 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 followings 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
----

See "`<<multiarch>>`", **dpkg-architecture**(1) and **dpkg-buildflags**(1).

[[newversion]]
=== New upstream release

When a new upstream release tarball **foo-**__newvwesion__**.tar.gz** is released, the Debian source package can be updated by invoking commands in the old source tree as:

----
$ uscan
 ... foo-newversion.tar.gz downloaded
$ uupdate -v newversion ../foo-newversion.tar.gz
----

* The *debian/watch* file in the old source tree must be a valid one.
* This make symlink **../foo_**__newvwesion__**.orig.tar.gz** pointing to **../foo-**__newvwesion__**.tar.gz**.
* Files are extracted from **../foo-**__newvwesion__**.tar.gz** to **../foo-**__newversion__**/**
* Files are copied from **../foo-**__oldversion__**/debian/** to **../foo-**__newvesion__**/debian/** .

After the above, you should refresh <<patches>> (see "`<<dquilt-manage>>`") 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.

[[dquilt-manage]]
=== Manage patch queue with *dquilt*

You can add, drop, and refresh <<patches>> 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:
+
--
----
$ dquilt push -a
$ dquilt new bugname.patch
$ dquilt add buggy_file
$ vim buggy_file
  ...
$ dquilt refresh
$ dquilt header -e
$ dquilt pop -a
----
--
* **Drop** (== disable) an existing patch
** Comment out pertinent line in *debian/patches/series*
** Erase the patch itself (optional)
* **Refresh** <<patches>> to make "`**dpkg-source -b**`" work as expected after updating a Debian package to the new upstream release.
+
--
----
 $ uscan; uupdate  # updating to the new upstream release
 $ while dquilt push; do dquilt refresh ; done
 $ dquilt pop -a
----
--
** If conflicts are encountered with "`**dquilt push**`" in the above, resolve them and run "`**dquilt refresh**`" manually for each of them.

[[build-commands]]
=== 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)

[[sbuild]]
=== 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:

----
 $ sudo sbuild -d unstable
----

In **schroot**(1) terminology, this builds a Debian package in a clean ephemeral https://en.wikipedia.org/wiki/Chroot[chroot] "`**chroot:unstable-amd64-sbuild**`" started as a copy of the clean minimal persistent https://en.wikipedia.org/wiki/Chroot[chroot] "`**source:unstable-amd64-sbuild**`".

This build environment was set up as described in "`<<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 newgrp -
----

//* This generated a configuration file **/etc/schroot/chroot.d/unstable-amd64-sbuild**__.$suffix__ holding the *schroot*(1) configuration *unstable-amd64-sbuild* :

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
----

Here:

* 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
----

TIP: 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.

[[special-cases]]
=== Special build cases

The *orig.tar.gz* 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*.

[[origtar]]
=== Upload *orig.tar.gz*

When you first upload the package to the archive, you need to include the original *orig.tar.gz* 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*
* For "`*gbp buildpackage*`", edit the *~/.gbp.conf* file.

TIP: On the other hand, the *-sd* option will force the exclusion of the original *orig.tar.gz* source.

TIP: Security uploads require including the *orig.tar.gz* file.

[[skipedupload]]
=== 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__
* For *gbp buildpackage*, edit the *~/.gbp.conf* file.

[[bug]]
=== 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 "`file:///usr/share/doc/reportbug/README.developers.gz[reportbug's Features for Developers] (**README.developers**)`"

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

