1DH(1) Debhelper DH(1)
2
6 dh - debhelper command sequencer
7
9 dh sequence [--with addon[,addon ...]] [--list] [debhelper options]
10
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
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 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 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 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 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 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 This feature is available since debhelper 8.9.7 (for override targets)
51 and 12.8 (for hook targets).
52 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 Note that the target has to be completely empty for this to work:
59 # Skip dh_bar - the good and optimized way
61 # Some rationale for skipping dh_bar goes here
62 override_dh_bar:
63 # 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 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 $ 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 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 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 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 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 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 # 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 # 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 # 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 These recipes are also relevant for conditional dependency targets,
150 which are often seen in a variant of the following example:
151 COND_TASKS =
153 ifneq (...)
154 COND_TASKS += maybe-run-this
155 endif
156 ...
157 maybe-run-this:
159 ...
160 # 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 # 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 # 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 When in doubt, pick the relevant SIMPLE case in the examples above that
191 match your need.
192
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 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 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 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 --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 --list, -l
230 List all available addons.
231 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 --no-act
237 Prints commands that would run for a given sequence, but does not
238 run them.
239 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 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
249 To see what commands are included in a sequence, without actually doing
250 anything:
251 dh binary-arch --no-act
253 This is a very simple rules file, for packages where the default
255 sequences of commands work with no additional options.
256 #!/usr/bin/make -f
258 %:
259 dh $@
260 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 #!/usr/bin/make -f
266 %:
267 dh $@
268 override_dh_strip:
270 dh_strip -Xfoo
271 override_dh_auto_configure:
273 dh_auto_configure -- --with-foo --disable-bar
274 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 #!/usr/bin/make -f
280 %:
281 dh $@
282 override_dh_auto_configure:
284 ./mondoconfig
285 override_dh_auto_build:
287 make universe-explode-in-delight
288 Another common case is wanting to do something manually before or after
290 a particular debhelper command is run.
291 #!/usr/bin/make -f
293 %:
294 dh $@
295 # Example assumes debhelper/12.8 and compat 10+
297 execute_after_dh_fixperms:
298 chmod 4755 debian/foo/usr/bin/foo
299 If you are on an older debhelper or compatibility level, the above
301 example would have to be written as.
302 #!/usr/bin/make -f
304 %:
305 dh $@
306 # 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 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 #!/usr/bin/make -f
316 %:
317 dh $@ --with python2
318 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 #!/usr/bin/make -f
324 %:
325 dh $@ --buildsystem=perl_build
326 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 #!/usr/bin/make -f
332 %:
333 dh $@ --sourcedirectory=src
334 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 #!/usr/bin/make -f
339 %:
340 dh $@ --builddirectory=build
341 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 #!/usr/bin/make -f
346 %:
347 dh $@ --parallel
348 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 #!/usr/bin/make -f
353 %:
354 dh $@ --no-parallel
355 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 #!/usr/bin/make -f
361 %:
362 dh $@
363 # Commands not to run:
365 override_dh_auto_test override_dh_compress override_dh_fixperms:
366 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 #!/usr/bin/make -f
372 %:
373 dh $@
374 override_dh_auto_build-indep:
376 $(MAKE) -C docs
377 # No tests needed for docs
379 override_dh_auto_test-indep:
380 override_dh_auto_install-indep:
382 $(MAKE) -C docs install
383 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 # Example assumes debhelper/12.8 and compat 10+
389 execute_after_dh_fixperms-arch:
390 chmod 4755 debian/foo/usr/bin/foo
391
393 The primary purpose of dh addons is to provide easy integration with
394 third-party provided features for debhelper. However, debhelper itself
395 also provide a few sequences that can be useful in some cases. These
396 are documented in this list:
397 build-stamp
399 A special addon for controlling whether dh (in compat 10 or later)
400 will create stamp files to tell whether the build target has been
401 run successfully. See "INTERNALS" for more details.
402 This addon is active by default but can disabled by using dh $@
404 --without build-stamp
405 dwz (obsolete)
407 Adds dh_dwz(1) to the sequence in compat level 11 or below.
408 Obsolete in compat 12 or later.
409 elf-tools
411 This addon adds tools related to ELF files to the sequence such as
412 dh_strip(1) and dh_shlibdeps(1)
413 This addon is conditionally active by default for architecture
415 specific packages - that is, it is skipped for arch:all packages.
416 In the special case where you need these tools to work on arch:all
417 packages, you can use --with elf-tools to activate it
418 unconditionally.
419 installinitramfs (obsolete)
421 Adds dh_installinitramfs(1) to the sequence in compat level 11 or
422 below. Obsolete in compat 12 or later.
423 root-sequence (internal)
425 This is reserved for internal usage.
426 single-binary
428 A special-purpose addon that makes debhelper run in "single binary"
429 mode.
430 When active, it will pass --destdir=debian/package/ to
432 dh_auto_install(1). This makes every file "installed" by the
433 upstream build system part of the (only) binary package by default
434 without having to use other helpers such as dh_install(1).
435 The addon will refuse to activate when the source package lists 2
437 or more binary packages in debian/control as a precaution.
438 Before compat 15. this behaviour was the default when there was
440 only a single binary package listed in debian/control. In compat
441 15 and later, this addon must explicitly be activated for this
442 feature to work.
443 The rationale for requiring this as an explicit choice is that if
445 it is implicit then debhelper will silently change behaviour on
446 adding a new binary package. This has caused many RC bugs when
447 maintainers renamed a binary and added transitional packages with
448 the intention of supporting seamless upgrades. The result would
449 often be two empty binary packages that were uploaded to archive
450 with users frustrated as their "upgrade" removed their programs.
451 systemd (obsolete)
453 Adds dh_systemd_enable(1) and dh_systemd_start(1) to the sequence
454 in compat level 10 or below. Obsolete in compat 11 or later.
455
457 If you're curious about dh's internals, here's how it works under the
458 hood.
459 In compat 10 (or later), dh creates a stamp file
461 debian/debhelper-build-stamp after the build step(s) are complete to
462 avoid re-running them. It is possible to avoid the stamp file by
463 passing --without=build-stamp to dh. This makes "no clean" builds
464 behave more like what some people expect at the expense of possibly
465 running the build and test twice (the second time as root or under
466 fakeroot(1)).
467 Inside an override target, dh_* commands will create a log file
469 debian/package.debhelper.log to keep track of which packages the
470 command(s) have been run for. These log files are then removed once
471 the override target is complete.
472 In compat 9 or earlier, each debhelper command will record when it's
474 successfully run in debian/package.debhelper.log. (Which dh_clean
475 deletes.) So dh can tell which commands have already been run, for
476 which packages, and skip running those commands again.
477 Each time dh is run (in compat 9 or earlier), it examines the log, and
479 finds the last logged command that is in the specified sequence. It
480 then continues with the next command in the sequence.
481 A sequence can also run dependent targets in debian/rules. For
483 example, the "binary" sequence runs the "install" target.
484 dh uses the DH_INTERNAL_OPTIONS environment variable to pass
486 information through to debhelper commands that are run inside override
487 targets. The contents (and indeed, existence) of this environment
488 variable, as the name might suggest, is subject to change at any time.
489 Commands in the build-indep, install-indep and binary-indep sequences
491 are passed the -i option to ensure they only work on architecture
492 independent packages, and commands in the build-arch, install-arch and
493 binary-arch sequences are passed the -a option to ensure they only work
494 on architecture dependent packages.
495
497 debhelper(7)
498 This program is a part of debhelper.
500
502 Joey Hess <joeyh@debian.org>
50313.5.2 2021-11-02 DH(1)