=== Debian packaging script

The Debian packaging script retargets the build systems to install files in the *$(DESTDIR)* and creates the archive file of the generated files as the *deb* file.  This *deb* file is used for the binary distribution and installed to the system using the *dpkg* command.

* *$(DESTDIR)=debian/*'binarypackage' : when building a single binary package, 'binarypackage'.
* *$(DESTDIR)=debian/tmp* : when building multiple binary packages.

==== The *dh* command

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

* *dh clean* : clean files in the source tree.
* *dh build* : build the source tree
* *dh build-arch* : build the source tree for architecture dependent packages
* *dh build-indep* : build the source tree for architecture independent packages
* *dh install* : install the binary files to *$(DESTDIR)*
* *dh install-arch* : install the binary files to *$(DESTDIR)* for architecture dependent packages
* *dh install-indep* : install the binary files to *$(DESTDIR)* for architecture independent packages
* *dh binary* : generate the *deb* file
* *dh binary-arch* : generate the *deb* file for architecture dependent packages
* *dh binary-indep* : generate the *deb* file for architecture independent packages

Thanks to this abstraction of the *dh* command footnote:[This simplicity is available since the *debhelper* version 7.  This document assumes that the *debhelper* version 9 or newer is used.], the Debian policy compliant *debian/rules* file supporting all the required targets can be written as simple as:

.Simple *debian/rules*:
----
%:
	dh $@
----

Essentially, this *dh* command calls all required *dh_** commands at the right moment.

The *debmake* command takes full advantage of this simple package building process enabled by the *debhelper* package for normal cases.

You still need to know how underlying build systems well for fixing bugs and making workarounds.

=== Package customization

There are some upstream sources which does not behave well and you may need to add customization to the build system of those upstream sources.

You have two approaches to customize the build system here:

* Apply modifications to the upstream source before building it.
** Set up *debian/patches/** with *-p1* patches and specify their sequence in *debian/series*
* Add customization to the Debian package build system.
** Set up "*debian/rules*" with appropriate *override_dh_** targets.
*** Whenever some special operation is required for a certain *dh_*'foo' command, any automatic execution of it can be overridden by adding the makefile target *override_dh_*'foo' in the *debian/rules* file.
** Add configuration files for the *debhelper* package in the *debian/* directory.
*** *debian/*'binarypackage'*.install*, *debian/*'binarypackage'*.link*, *debian/*'binarypackage'*.manpages*, *debian/*'binarypackage'*.docs*, ...

=== Splitting the package

Sometimes, it is better to split the generated binary package into small ones.  This can be easily realized:

* by creating binary package entries for all binary packages in the *debian/control* file, and 
* by listing all file pathes (relative to *debian/tmp*) in the *debian/*'binarypackage'**.install** files.

See *dh_install*(1).  

=== Upstream build systems

upstream build systems go through several steps to install generated binary files to the system from the source distribution.

==== Autotools

Autotools (*autoconf* + *automake*) has 4 steps.

1. setup the build system ("*vim configure.ac Makefile.am*" and "*autoreconf -ivf*")
2. configure the build system ("*./configure*")
3. build the source tree ("*make*")
4. install the binary files ("*make install*")

The upstream usually performs the step 1 and builds the upstream tarball for distribution using the "*make dist*" command.

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

The package maintainer wishes to take care step 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 porting supports.

==== Python distutils

Python distutils has 3 steps.

1. setup and configure the build system ("*vim setup.py*")
2. build the source tree ("*python setup.py build*")
3. install the binary files ("*python setup.py install*")

The upstream usually performs the step 1 and builds the upstream tarball for distribution using the "*python setup.py sdist*" command.

The package maintainer needs to take care step 2.  This is realized simply by the "*dh $@*" command used in the *debian/rules* file, after *jessie*.


