[[rules]]
=== debian/rules

The *debian/rules* script is the executable script to build the Debian package.

* The *debian/rules* script re-targets the upstream build system (see <<build>>) to install files in the **$(DESTDIR)** and creates the archive file of the generated files as the *deb* file.  
** The *deb* file is used for the binary distribution and installed to the system using the *dpkg* command.
* The *dh* command is normally used as the front-end to the build system inside the *debian/rules* script.
* **$(DESTDIR)** path depends on the build type.
** **$(DESTDIR)=debian/**'binarypackage'  (single binary package)
** **$(DESTDIR)=debian/tmp**  (multiple binary package)

[[dh]]
==== dh

The *dh* command from the *debhelper* package with the help from its associated packages functions as the wrapper to the typical upstream 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

[[simplerules]]
==== Simple debian/rules

Thanks to this abstraction of the *dh* command footnote:[This simplicity is available since the version 7 of the *debhelper* package.  This guide assumes the use of the *debhelper* version 9 or newer.], the Debian policy compliant *debian/rules* file supporting all the required targets can be written as simple as footnote::[The *debmake* command generates a bit more complicated *debian/rules* file.  But this is the core part.]:

.Simple *debian/rules*:
----
#!/usr/bin/make -f
#DH_VERBOSE = 1

%:
	dh $@
----

Essentially, this *dh* command functions as the sequencer to call all required *dh_** commands at the right moment.

NOTE: The *debmake* command sets the *debian/control* file with "*Build-Depends: debhelper (>=9)*".

TIP: Setting "`DH_VERBOSE = 1`" outputs every command that modifies files on
the build system.  Also it enables verbose build logs for some build systems.

[[customrules]]
==== Customized debian/rules

Flexible customization of the *debian/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 *debmake* command creates the initial template file taking advantage of the above simple *debian/rules* while adding some extra customizations for the package hardening, etc.

You need to know how underlying build systems work under the hood (see <<build>>) to address their irregularities using the package customization.

See <<simple>> for the actual simple *debian/rules* generated by the *debmake* command which comes with the commented out parts addressing the hardening via compile options (see <<harden>>) and the multiarch customization (see <<multiarch>>).

[[buildflags]]
==== Variables for debian/rules

You may set the buildflag variables such as *CPPFLAGS*, *CFLAGS*, *LDFLAGS*, etc. and other convenient variables for the build architecture, the package version, and the vender name simply by including the following in the *debian/rules* file.

----------------
DPKG_EXPORT_BUILDFLAGS = 1
include /usr/share/dpkg/default.mk
----------------

Advantage of setting these buildflag variables are the following:

* consistent build result
** *dpkg-buildpackage* vs. *debian/rules*
* distribution specific build support
** Debian, Ubuntu, ...
* architecture specific build support
** mix of arch=*any*, arch=*linux-any*, etc. binary packages
* backport build support

See *dpkg-buildflags*(8) and read the files in the */usr/share/dpkg* directory.


