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

Let's recap the customization of the Debian packaging.

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

* 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 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, the modification 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>>).  A 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 the future upgrades in this way.

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

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

Typically, https://en.wikipedia.org/wiki/Git[Git] is used as 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 untared from the released upstream tarball.

TIP: It's a good idea to add the *.gitignore* file 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 untared from the released upstream tarball.

Adding few extra files in *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*, ...) to 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 publically accessible.

WARNING: The *debian/source/local-options* and *debian/source/local-patch-header* files are not included in the Debian source package and are meant to be recorded in the VCS.

[[rebuild]]
=== Rebuilding non-native package without extraneous diffs

The upstream source tarball may contain some auto-generated files which are overwritten by the build process.  When the package is rebuilt from the same source tree, the generated Debian source package may contain extraneous diffs for such auto-generated files.

Inclusion of such unneeded diffs makes it difficult to review the package and should be avoided.  There are a few methods to fix this problem.

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

The problem of extraneous diffs can be fixed by removing such auto-generated files in the ``*debian/rules clean*'' target.

This is because 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 diffs 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 simple *-i* option is set if you followed <<devscripts-setup>> to make the *dpkg-source* command skip making diffs for the typical VCS files in the source tree.  The actual default regex used by the simple *-i* option can be found by in the ``*dpkg-source -h*'' output.

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

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

The problem of extraneous diffs can be fixed by ignoring changes made to parts of the source tree using the *--extend-diff-ignore* option of the *dpkg-source*(1) command.

For example, in order to ignore changes to the *config.sub*, *config.guess* and *Makefile* files, their matching regex can be added to the *debian/source/options* file as:

----
# 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 non-standard VCS files interfere with your packaging, you can ignore such files by tweaking the regex by adding the ``*extend-diff-ignore=...*'' line in the *debian/source/local-options* file.

[[tar-ignore]]
=== Native Debian source package without extraneous files

If you are making the native Debian source package instead of the normal non-native Debian source package and wish to exclude some files in the source tree from the generated tarball, you can exclude such files by tweaking the file glob.

Normally, changing the <<devscripts-setup>> example to use ``*DEBUILD_DPKG_BUILDPACKAGE_OPTS="-i -I -us -uc"*'' should give decent default globs.  The actual default globs used by the simple *-I* option can be found by in the ``*dpkg-source -h*'' output.

If, for example, the source package needs ***.o** as a part of the test data, the default globs may be problematic.  You can work around this problem by adding the ``**tar-ignore=...**'' lines in the **debian/source/local-options** file to customize the globs for each package to work around this problem.

