[[custom]]
=== Customization of the Debian packaging

Let's recap the customization of the Debian packaging.

All customization data for the Debian package resides in the *debian/* directory.  A simple example is given in <<step-maintainer>>.  Normally, this customization involves a combination of the following:

* The Debian package build system can be customized through the *debian/rules* file (see <<customrules>>).
* 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, modifications to the upstream source recorded as the *-p1* patches in the *debian/patches/* directory is deployed.  These patches are applied in the sequence defined in the *debian/patches/series* file before building the package (see <<patches>>).  Simple examples are given 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.

[[vcs]]
=== Recording in VCS (standard)

Typically, https://en.wikipedia.org/wiki/Git[Git] is used as the https://en.wikipedia.org/wiki/Version_control[VCS] to record the Debian packaging activity with the following branches.

* *master* branch
** Record the source tree used for the Debian packaging.
** The upstream portion of the source tree is recorded unmodified.
** The upstream modifications for the Debian packaging are recorded in the *debian/patches/* directory as the *-p1* patches.
* *upstream* branch
** Record the upstream source tree untarred from the released upstream tarball.

TIP: It's a good idea to add to the *.gitignore* file the listing *.pc*.

TIP: Add *unapply-patches* and *abort-on-upstream-changes* lines to the *debian/source/local-options* file to keep the upstream portion unmodified.

TIP: You may also track the upstream VCS data with a branch different from the *upstream* branch to ease cherry-picking of patches.

[[alt-vcs]]
=== Recording in VCS (alternative)

You may not wish to keep up with creating the *-p1* patch files for all upstream changes needed.  You can record the Debian packaging activity with the following branches.

* *master* branch
** Record the source tree used for the Debian packaging.
** The upstream portion of the source tree is recorded with modifications for the Debian packaging.
* *upstream* branch
** Record the upstream source tree untarred from the released upstream tarball.

Adding a few extra files in the *debian/* directory enables you to do this.

-----
 $ tar -xvzf <package-version>.tar.gz
 $ ln -sf <package_version>.orig.tar.gz
 $ cd <package-version>/
 ... hack...hack...
 $ echo "single-debian-patch" >> debian/source/local-options
 $ cat >debian/source/local-patch-header <<END
 This patch contains all the Debian-specific changes mixed
 together. To review them separately, please inspect the VCS
 history at https://git.debian.org/?=collab-maint/foo.git.
-----

Let the *dpkg-source* command invoked by the Debian package build process (*dpkg-buildpackage*, *debuild*, ...) generate the *-p1* patch file *debian/patches/debian-changes* automatically.

TIP: This approach can be adopted for any VCS tools.  Since this approach merges all changes into a merged patch, it is desirable to keep the VCS data publicly accessible.

TIP: The *debian/source/local-options* and *debian/source/local-patch-header* files are meant to be recorded in the VCS.  These aren't included in the Debian source package.

[[build-noextra]]
=== Building package without extraneous contents

There are a few cases which cause the inclusion of undesirable contents in the generated Debian source package.

* The upstream source tree may be placed under the version control system.  When the package is rebuilt from this source tree, the generated Debian source package contains extraneous contents from the version control system files.
* The upstream source tree may contain some auto-generated files.  When the package is rebuilt from this source tree, the generated Debian source package contains extraneous contents from the auto-generated files.

Normally, the *-i* and *-I* options set in <<devscripts-setup>> for the *dpkg-source* command should avoid these.  Here, the *-i* option is aimed at the non-native package while the *-I* is aimed at the native package.  See *dpkg-source*(1) and the ``*dpkg-source --help*'' output.

There are several methods to avoid inclusion of undesirable contents.

[[rules-clean]]
==== Fix by debian/rules clean

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.

[[git-clean]]
==== Fix using VCS

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

This works because the *dpkg-source* command ignores the contents of the typical VCS files in the source tree with the *DEBUILD_DPKG_BUILDPACKAGE_OPTS* setting in <<devscripts-setup>>.

TIP: If the source tree is not managed by a VCS, you should run ``*git init; git add -A .; git commit*'' before the first build.

[[extend-diff-ignore]]
==== Fix by extend-diff-ignore

This is for a non-native package.

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.

[[tar-ignore]]
==== Fix by tar-ignore

This is for a native package.

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 <<devscripts-setup>> is too aggressive.  You can work around this problem by dropping the *-I* option for *DEBUILD_DPKG_BUILDPACKAGE_OPTS* in <<devscripts-setup>> while adding the ``*tar-ignore=...*'' lines in the *debian/source/local-options* file for each package.