1DH(1)                              Debhelper                             DH(1)
2
3
4

NAME

6       dh - debhelper command sequencer
7

SYNOPSIS

9       dh sequence [--with addon[,addon ...]] [--list] [debhelperĀ options]
10

DESCRIPTION

12       dh runs a sequence of debhelper commands. The supported sequences
13       correspond to the targets of a debian/rules file: build-arch, build-
14       indep, build, clean, install-indep, install-arch, install, binary-arch,
15       binary-indep, and binary.
16

OVERRIDE AND HOOK TARGETS

18       A debian/rules file using dh can override the command that is run at
19       any step in a sequence, by defining an override target.  It is also
20       possible to inject a command before or after any step without affecting
21       the step itself.
22
23   Injecting commands before or after a step
24       Note: This feature requires debhelper 12.8 or later plus the package
25       must use compatibility mode 10 or later.
26
27       To inject commands before dh_command, add a target named
28       execute_before_dh_command to the rules files.  Similarly, if you want
29       to inject commands after dh_command, add the target
30       execute_after_dh_command.  Both targets can be used for the same
31       dh_command and also even if the command is overridden (as described in
32       "Overriding a command" below).
33
34       When these targets are defined, dh will call the targets respectively
35       before or after it would invoke dh_command (or its override target).
36
37   Overriding a command
38       To override dh_command, add a target named override_dh_command to the
39       rules file. When it would normally run dh_command, dh will instead call
40       that target. The override target can then run the command with
41       additional options, or run entirely different commands instead. See
42       examples below.
43
44   Architecture dependent/independent override and hook targets
45       The override and hook targets can also be defined to run only when
46       building architecture dependent or architecture independent packages.
47       Use targets with names like override_dh_command-arch and
48       execute_afterdh_command-indep.
49
50       This feature is available since debhelper 8.9.7 (for override targets)
51       and 12.8 (for hook targets).
52
53   Completely empty targets
54       As a special optimization, dh will skip a target if it is completely
55       empty.  This is mostly useful for override targets, where the command
56       will simply be skipped without the overhead of invoking a dummy target.
57
58       Note that the target has to be completely empty for this to work:
59
60            # Skip dh_bar - the good and optimized way
61            # Some rationale for skipping dh_bar goes here
62            override_dh_bar:
63
64
65            # Skip dh_foo - the slow way
66            override_dh_foo:
67               # Some rationale for skipping dh_foo goes here
68               # (these comments causes a dummy target to be run)
69
70   Verifying targets are picked up by dh
71       If you want to confirm that dh has seen an override or a hook target,
72       you can use the following command as an example:
73
74           $ dh binary --no-act | grep dh_install | head -n5
75                dh_installdirs
76                dh_install
77                debian/rules execute_after_dh_install
78                dh_installdocs
79                dh_installchangelogs
80
81       The debian/rules execute_after_dh_install in the output, which signals
82       that dh registered a execute_after_dh_install target and would run it
83       directly after dh_install(1).
84
85       Note that "Completely empty targets" will be omitted in the listing
86       above.  This makes it a bit harder to spot as you are looking for the
87       omission of a command name.  But otherwise, the principle remains the
88       same.
89
90   Caveats with hook targets and makefile conditionals
91       If you choose to wrap a hook target in makefile conditionals, please be
92       aware that dh computes all the hook targets a head of time and caches
93       the result for that run.  Furthermore, the conditionals will be invoked
94       again when dh calls the hook target later and will assume the answer
95       did not change.
96
97       The parsing and caching often happens before dh knows whether it will
98       build arch:any (-a) or/and arch:all (-i) packages, which can produce
99       confusing results - especially when dh_listpackages(1) is part of the
100       conditional.
101
102       Most of the problems can be avoided by making the hook target
103       unconditional and then have the "body" be partially or completely
104       conditional.  As an example:
105
106             # SIMPLE: It is well-defined what happens.  The hook target
107             # is always considered.  The "maybe run this" bit is
108             # conditional but dh_foo is definitely skipped.
109             #
110             # Note: The conditional is evaluated "twice" where its
111             # influences what happens.  Once when dh check which hook
112             # targets exist and once when the override_dh_foo hook target
113             # is run.  If *either* times return false, "maybe run this"
114             # is skipped.
115             override_dh_foo:
116             ifneq (...)
117                 maybe run this
118             endif
119
120             # SIMPLE: This is also well-defined.  The hook target is always
121             # run and dh_bar is skipped.  The "maybe run this" bit is
122             # conditional as one might expect.
123             #
124             # Note: The conditional is still evaluated multiple times (in
125             # different process each time).  However, only the evaluation
126             # that happens when the hook target is run influences what
127             # happens.
128             override_dh_bar:
129                 : # Dummy command to force the target to always be run
130             ifneq (...)
131                 maybe run this
132             endif
133
134
135             # COMPLICATED: This case can be non-trivial and have sharp edges.
136             # Use at your own peril if dh_listpackages in the conditional.
137             #
138             # Here, either dh_baz is run normally OR "maybe run this" is run
139             # instead.
140             #
141             # And it gets even more complicated to reason about if dh needs to
142             # recurse into debian/rules because you have an "explicit"
143             # standard target (e.g. a "build-arch:" target separate from "%:").
144             ifneq (...)
145             override_dh_baz:
146                 maybe run this
147             endif
148
149       These recipes are also relevant for conditional dependency targets,
150       which are often seen in a variant of the following example:
151
152             COND_TASKS =
153             ifneq (...)
154             COND_TASKS += maybe-run-this
155             endif
156             ...
157
158             maybe-run-this:
159                 ...
160
161             # SIMPLE: It is well-defined what happens.  Either the
162             # $(COND_TASKS) are skipped or run.
163             #
164             # Note: The conditional is evaluated "twice" where its
165             # influences what happens.  Once when dh check which hook
166             # targets exist and once when the override_dh_foo hook target
167             # is run.  If *either* times return false, $(COND_TASKS)
168             # is skipped.
169             override_dh_foo: $(COND_TASKS)
170
171
172             # SIMPLE: This is also well-defined.  The hook target is always
173             # run and dh_bar is skipped.  The $(COND_TASKS) bit is
174             # conditional as one might expect.
175             #
176             # Note: The conditional is still evaluated multiple times (in
177             # different process each time).  However, only the evaluation
178             # that happens when the hook target is run influences what
179             # happens.
180             override_dh_bar: $(COND_TASKS)
181                 : # Dummy command to force the target to always be run
182
183             # COMPLICATED: This case can be non-trivial and have sharp edges.
184             # Use at your own peril if dh_listpackages in the conditional.
185             #
186             ifneq (...)
187             override_dh_baz: $(COND_TASKS)
188             endif
189
190       When in doubt, pick the relevant SIMPLE case in the examples above that
191       match your need.
192

OPTIONS

194       --with addon[,addon ...]
195           Add the debhelper commands specified by the given addon to
196           appropriate places in the sequence of commands that is run. This
197           option can be repeated more than once, or multiple addons can be
198           listed, separated by commas.  This is used when there is a third-
199           party package that provides debhelper commands. See the PROGRAMMING
200           file for documentation about the sequence addon interface.
201
202           A Build-Depends relation on the package dh-sequence-addon implies a
203           --with addon. This avoids the need for an explicit --with in
204           debian/rules that only duplicates what is already declared via the
205           build dependencies in debian/control.  The relation can (since
206           12.5) be made optional via e.g.  build-profiles.  This enables you
207           to easily disable an addon that is only useful with certain
208           profiles (e.g. to facilitate bootstrapping).
209
210           Since debhelper 12.5, addons can also be activated in indep-only
211           mode (via Build-Depends-Indep) or arch-only mode (via Build-
212           Depends-Arch). Such addons are only active in the particular
213           sequence (e.g. binary-indep) which simplifies dependency management
214           for cross-builds.
215
216           Please note that addons activated via Build-Depends-Indep or Build-
217           Depends-Arch are subject to additional limitations to ensure the
218           result is deterministic even when the addon is unavailable (e.g.
219           during clean).  This implies that some addons are incompatible with
220           these restrictions and can only be used via Build-Depends (or
221           manually via debian/rules).  Currently, such addons can only add
222           commands to sequences.
223
224       --without addon
225           The inverse of --with, disables using the given addon. This option
226           can be repeated more than once, or multiple addons to disable can
227           be listed, separated by commas.
228
229       --list, -l
230           List all available addons.
231
232           When called only with this option, dh can be called from any
233           directory (i.e. it does not need access to files from a source
234           package).
235
236       --no-act
237           Prints commands that would run for a given sequence, but does not
238           run them.
239
240           Note that dh normally skips running commands that it knows will do
241           nothing.  With --no-act, the full list of commands in a sequence is
242           printed.
243
244       Other options passed to dh are passed on to each command it runs. This
245       can be used to set an option like -v or -X or -N, as well as for more
246       specialised options.
247

EXAMPLES

249       To see what commands are included in a sequence, without actually doing
250       anything:
251
252               dh binary-arch --no-act
253
254       This is a very simple rules file, for packages where the default
255       sequences of commands work with no additional options.
256
257               #!/usr/bin/make -f
258               %:
259                       dh $@
260
261       Often you'll want to pass an option to a specific debhelper command.
262       The easy way to do with is by adding an override target for that
263       command.
264
265               #!/usr/bin/make -f
266               %:
267                       dh $@
268
269               override_dh_strip:
270                       dh_strip -Xfoo
271
272               override_dh_auto_configure:
273                       dh_auto_configure -- --with-foo --disable-bar
274
275       Sometimes the automated dh_auto_configure(1) and dh_auto_build(1) can't
276       guess what to do for a strange package. Here's how to avoid running
277       either and instead run your own commands.
278
279               #!/usr/bin/make -f
280               %:
281                       dh $@
282
283               override_dh_auto_configure:
284                       ./mondoconfig
285
286               override_dh_auto_build:
287                       make universe-explode-in-delight
288
289       Another common case is wanting to do something manually before or after
290       a particular debhelper command is run.
291
292               #!/usr/bin/make -f
293               %:
294                       dh $@
295
296               # Example assumes debhelper/12.8 and compat 10+
297               execute_after_dh_fixperms:
298                       chmod 4755 debian/foo/usr/bin/foo
299
300       If you are on an older debhelper or compatibility level, the above
301       example would have to be written as.
302
303               #!/usr/bin/make -f
304               %:
305                       dh $@
306
307               # Older debhelper versions or using compat 9 or lower.
308               override_dh_fixperms:
309                       dh_fixperms
310                       chmod 4755 debian/foo/usr/bin/foo
311
312       Python tools are not run by dh by default, due to the continual change
313       in that area. Here is how to use dh_python2.
314
315               #!/usr/bin/make -f
316               %:
317                       dh $@ --with python2
318
319       Here is how to force use of Perl's Module::Build build system, which
320       can be necessary if debhelper wrongly detects that the package uses
321       MakeMaker.
322
323               #!/usr/bin/make -f
324               %:
325                       dh $@ --buildsystem=perl_build
326
327       Here is an example of overriding where the dh_auto_* commands find the
328       package's source, for a package where the source is located in a
329       subdirectory.
330
331               #!/usr/bin/make -f
332               %:
333                       dh $@ --sourcedirectory=src
334
335       And here is an example of how to tell the dh_auto_* commands to build
336       in a subdirectory, which will be removed on clean.
337
338               #!/usr/bin/make -f
339               %:
340                       dh $@ --builddirectory=build
341
342       If your package can be built in parallel, please either use compat 10
343       or pass --parallel to dh. Then dpkg-buildpackage -j will work.
344
345               #!/usr/bin/make -f
346               %:
347                       dh $@ --parallel
348
349       If your package cannot be built reliably while using multiple threads,
350       please pass --no-parallel to dh (or the relevant dh_auto_* command):
351
352               #!/usr/bin/make -f
353               %:
354                       dh $@ --no-parallel
355
356       Here is a way to prevent dh from running several commands that you
357       don't want it to run, by defining empty override targets for each
358       command.
359
360               #!/usr/bin/make -f
361               %:
362                       dh $@
363
364               # Commands not to run:
365               override_dh_auto_test override_dh_compress override_dh_fixperms:
366
367       A long build process for a separate documentation package can be
368       separated out using architecture independent overrides.  These will be
369       skipped when running build-arch and binary-arch sequences.
370
371               #!/usr/bin/make -f
372               %:
373                       dh $@
374
375               override_dh_auto_build-indep:
376                       $(MAKE) -C docs
377
378               # No tests needed for docs
379               override_dh_auto_test-indep:
380
381               override_dh_auto_install-indep:
382                       $(MAKE) -C docs install
383
384       Adding to the example above, suppose you need to chmod a file, but only
385       when building the architecture dependent package, as it's not present
386       when building only documentation.
387
388               # Example assumes debhelper/12.8 and compat 10+
389               execute_after_dh_fixperms-arch:
390                       chmod 4755 debian/foo/usr/bin/foo
391

INTERNALS

393       If you're curious about dh's internals, here's how it works under the
394       hood.
395
396       In compat 10 (or later), dh creates a stamp file
397       debian/debhelper-build-stamp after the build step(s) are complete to
398       avoid re-running them.  It is possible to avoid the stamp file by
399       passing --without=build-stamp to dh.  This makes "no clean" builds
400       behave more like what some people expect at the expense of possibly
401       running the build and test twice (the second time as root or under
402       fakeroot(1)).
403
404       Inside an override target, dh_* commands will create a log file
405       debian/package.debhelper.log to keep track of which packages the
406       command(s) have been run for.  These log files are then removed once
407       the override target is complete.
408
409       In compat 9 or earlier, each debhelper command will record when it's
410       successfully run in debian/package.debhelper.log. (Which dh_clean
411       deletes.) So dh can tell which commands have already been run, for
412       which packages, and skip running those commands again.
413
414       Each time dh is run (in compat 9 or earlier), it examines the log, and
415       finds the last logged command that is in the specified sequence. It
416       then continues with the next command in the sequence.
417
418       A sequence can also run dependent targets in debian/rules.  For
419       example, the "binary" sequence runs the "install" target.
420
421       dh uses the DH_INTERNAL_OPTIONS environment variable to pass
422       information through to debhelper commands that are run inside override
423       targets. The contents (and indeed, existence) of this environment
424       variable, as the name might suggest, is subject to change at any time.
425
426       Commands in the build-indep, install-indep and binary-indep sequences
427       are passed the -i option to ensure they only work on architecture
428       independent packages, and commands in the build-arch, install-arch and
429       binary-arch sequences are passed the -a option to ensure they only work
430       on architecture dependent packages.
431

SEE ALSO

433       debhelper(7)
434
435       This program is a part of debhelper.
436

AUTHOR

438       Joey Hess <joeyh@debian.org>
439
440
441
44213.3.4                            2021-05-13                             DH(1)
Impressum