1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
|
[[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 help from its associated packages functions as the wrapper to the typical upstream build systems and offers us 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
NOTE: For *debhelper* ``compat >= 9'', the *dh* command exports compiler flags (*CFLAGS*, *CXXFLAGS*, *FFLAGS*, *CPPFLAGS* and *LDFLAGS*) with values as returned by *dpkg-buildflags* if they are not set previously. (The *dh* command calls *set_buildflags* defined in the *Debian::Debhelper::Dh_Lib* module.)
[[simplerules]]
==== Simple debian/rules
Thanks to this abstraction of the *dh* command footnote:[This simplicity is available since version 7 of the *debhelper* package. This guide assumes the use of *debhelper* version @@@dhcompat@@@ 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
#export DH_VERBOSE = 1
%:
dh $@
----
Essentially, this *dh* command functions as the sequencer to call all required *dh_** commands at the right moment.
TIP: Setting ``*export 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* script 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**,
* **setup.py**, or
* **Build.PL**.
If this is the case, you should add the *override_dh_auto_build* target and executing the ``*dh_auto_build --* 'arguments''' command. This ensures passing 'arguments' to the such build system after the default parameters that *dh_auto_build* usually passes.
TIP: Please try not to execute the above build system commands directly if they are supported by the *dh_auto_build* command.
The *debmake* command creates the initial template file taking advantage of the above simple *debian/rules* file example while adding some extra customizations for package hardening, etc. You need to know how underlying build systems work under the hood (see <<build>>) to address their irregularities using package customization.
* See <<step-maintainer>> for basic customization of the template *debian/rules* file generated by the *debmake* command.
* See <<multiarch>> for multiarch customization.
* See <<harden>> for hardening customization.
[[variablesrules]]
==== 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*::
*DEB_SOURCE*, *DEB_VERSION*, *DEB_VERSION_EPOCH_UPSTREAM*, *DEB_VERSION_UPSTREAM_REVISION*, *DEB_VERSION_UPSTREAM*, and *DEB_DISTRIBUTION* variables.
+
These are useful for backport support etc..
*vendor.mk*::
*DEB_VENDOR* and *DEB_PARENT_VENDOR* variables; and *dpkg_vendor_derives_from* macro.
+
These are useful for vendor support (Debian, Ubuntu, ...).
*architecture.mk*::
Set **DEB_HOST_*** and **DEB_BUILD_*** variables.
+
An alternative method of retrieving those variables is to invoke *dpkg-architecture* directly and query the value of a single variable. With explicit invocation of *dpkg-architecture* to retrieve necessary variables, there is no need to include *architecture.mk* in *debian/rules*, which would import all architecture-related variables.
*buildflags.mk*::
Set *CFLAGS*, *CPPFLAGS*, *CXXFLAGS*, *OBJCFLAGS*, *OBJCXXFLAGS*, *GCJFLAGS*, *FFLAGS*, *FCFLAGS*, and *LDFLAGS* build flags.
If you wish to use some of these useful variables in *debian/rules*, copy relevant code to *debian/rules* or write a simpler alternative in it. Please keep *debian/rules* simple.
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
----
TIP: It was useful to include *buildflags.mk* in *debian/rules* to set the build flags such as *CPPFLAGS*, *CFLAGS*, *LDFLAGS*, etc. properly while honoring *DEB_CFLAGS_MAINT_APPEND*, *DEB_BUILD_MAINT_OPTIONS*, etc. for the *debhelper* ``compat \<= 8''. Now you should use the *debhelper* ``compat >= 9'', should not include *buildflags.mk* without specific reasons, and should let the *dh* command set these build flags.
See <<multiarch>>, *dpkg-architecture*(1) and *dpkg-buildflags*(1).
[[reproducible]]
==== Reproducible build
Here are some recommendations to attain a reproducible build result.
* Don't embed the timestamp based on the system time.
* Use ``*dh $@*'' in the *debian/rules* to access the latest *debhelper* features.
* Export the build environment as ``*LC_ALL=C.UTF-8*'' (see <<utf-8-build>>).
* Set the timestamp used in the upstream source from the value of the debhelper-provided environment variable *$SOURCE_DATE_EPOCH*.
* Read more at https://wiki.debian.org/ReproducibleBuilds[ReproducibleBuilds].
** https://wiki.debian.org/ReproducibleBuilds/Howto[ReproducibleBuilds Howto].
** https://wiki.debian.org/ReproducibleBuilds/TimestampsProposal[ReproducibleBuilds TimestampsProposal].
The control file 'source-name_source-version_arch'*.buildinfo* generated by *dpkg-genbuildinfo*(1) records the build environment. See *deb-buildinfo*(5)
|
