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_after_dh_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 and does not depend on any other target. This is mostly useful
56 for override targets, where the command will simply be skipped without
57 the overhead of invoking a dummy target.
58 Note that the target has to be completely empty for this to work:
60 # Skip dh_bar - the good and optimized way
62 # Some rationale for skipping dh_bar goes here
63 override_dh_bar:
64 # Skip dh_foo - the slow way
67 override_dh_foo:
68 # Some rationale for skipping dh_foo goes here
69 # (these comments causes a dummy target to be run)
70 Verifying targets are picked up by dh
72 As of debhelper 13.10, you can use dh_assistant(1) to see which
73 override and hook targets will be seen by dh. Here is an example run
74 of dh_assistant(1) along with its output:
75 $ dh_assistant detect-hook-targets
77 {
78 "commands-not-in-path": [
79 "dh_foo"
80 ],
81 "hook-targets": [
82 {
83 "command": "dh_strip_nondeterminism",
84 "is-empty": true,
85 "package-section-param": null,
86 "target-name": "override_dh_strip_nondeterminism"
87 },
88 {
89 "command": "dh_foo",
90 "is-empty": false,
91 "package-section-param": "-a",
92 "target-name": "override_dh_foo-arch"
93 }
94 ]
95 }
96 The commands-not-in-path is useful for spotting mistakes in the hook
98 target names. A non-empty value implies one of more hook targets are
99 related to a command that is either not installed or no command with
100 that name exists at all. It is generally worth double checking these.
101 Additionally, the is-empty attribute for each hook target can be used
103 for seeing whether a hook target triggers the "Completely empty
104 targets" optimization.
105 If you are interested in the other attributes, please read the
107 dh_assistant(1) for the details.
108 Verifying targets are picked up by dh (when debhelper is older than
110 13.10)
111 On older versions of debhelper, you have to use dh with --no-act. You
113 can use the following command as an example:
114 $ dh binary --no-act | grep dh_install | head -n5
116 dh_installdirs
117 dh_install
118 debian/rules execute_after_dh_install
119 dh_installdocs
120 dh_installchangelogs
121 The debian/rules execute_after_dh_install in the output, which signals
123 that dh registered a execute_after_dh_install target and would run it
124 directly after dh_install(1).
125 Note that "Completely empty targets" will be omitted in the listing
127 above. This makes it a bit harder to spot as you are looking for the
128 omission of a command name. But otherwise, the principle remains the
129 same.
130 Caveats with hook targets and makefile conditionals
132 If you choose to wrap a hook target in makefile conditionals, please be
133 aware that dh computes all the hook targets a head of time and caches
134 the result for that run. Furthermore, the conditionals will be invoked
135 again when dh calls the hook target later and will assume the answer
136 did not change.
137 The parsing and caching often happens before dh knows whether it will
139 build arch:any (-a) or/and arch:all (-i) packages, which can produce
140 confusing results - especially when dh_listpackages(1) is part of the
141 conditional.
142 Most of the problems can be avoided by making the hook target
144 unconditional and then have the "body" be partially or completely
145 conditional. As an example:
146 # SIMPLE: It is well-defined what happens. The hook target
148 # is always considered. The "maybe run this" bit is
149 # conditional but dh_foo is definitely skipped.
150 #
151 # Note: The conditional is evaluated "twice" where its
152 # influences what happens. Once when dh check which hook
153 # targets exist and once when the override_dh_foo hook target
154 # is run. If *either* times return false, "maybe run this"
155 # is skipped.
156 override_dh_foo:
157 ifneq (...)
158 maybe run this
159 endif
160 # SIMPLE: This is also well-defined. The hook target is always
162 # run and dh_bar is skipped. The "maybe run this" bit is
163 # conditional as one might expect.
164 #
165 # Note: The conditional is still evaluated multiple times (in
166 # different process each time). However, only the evaluation
167 # that happens when the hook target is run influences what
168 # happens.
169 override_dh_bar:
170 : # Dummy command to force the target to always be run
171 ifneq (...)
172 maybe run this
173 endif
174 # COMPLICATED: This case can be non-trivial and have sharp edges.
177 # Use at your own peril if dh_listpackages in the conditional.
178 #
179 # Here, either dh_baz is run normally OR "maybe run this" is run
180 # instead.
181 #
182 # And it gets even more complicated to reason about if dh needs to
183 # recurse into debian/rules because you have an "explicit"
184 # standard target (e.g. a "build-arch:" target separate from "%:").
185 ifneq (...)
186 override_dh_baz:
187 maybe run this
188 endif
189 These recipes are also relevant for conditional dependency targets,
191 which are often seen in a variant of the following example:
192 COND_TASKS =
194 ifneq (...)
195 COND_TASKS += maybe-run-this
196 endif
197 ...
198 maybe-run-this:
200 ...
201 # SIMPLE: It is well-defined what happens. Either the
203 # $(COND_TASKS) are skipped or run.
204 #
205 # Note: The conditional is evaluated "twice" where its
206 # influences what happens. Once when dh check which hook
207 # targets exist and once when the override_dh_foo hook target
208 # is run. If *either* times return false, $(COND_TASKS)
209 # is skipped.
210 override_dh_foo: $(COND_TASKS)
211 # SIMPLE: This is also well-defined. The hook target is always
214 # run and dh_bar is skipped. The $(COND_TASKS) bit is
215 # conditional as one might expect.
216 #
217 # Note: The conditional is still evaluated multiple times (in
218 # different process each time). However, only the evaluation
219 # that happens when the hook target is run influences what
220 # happens.
221 override_dh_bar: $(COND_TASKS)
222 : # Dummy command to force the target to always be run
223 # COMPLICATED: This case can be non-trivial and have sharp edges.
225 # Use at your own peril if dh_listpackages in the conditional.
226 #
227 ifneq (...)
228 override_dh_baz: $(COND_TASKS)
229 endif
230 When in doubt, pick the relevant SIMPLE case in the examples above that
232 match your need.
233
235 --with addon[,addon ...]
236 Add the debhelper commands specified by the given addon to
237 appropriate places in the sequence of commands that is run. This
238 option can be repeated more than once, or multiple addons can be
239 listed, separated by commas. This is used when there is a third-
240 party package that provides debhelper commands. See the PROGRAMMING
241 file for documentation about the sequence addon interface.
242 A Build-Depends relation on the package dh-sequence-addon implies a
244 --with addon. This avoids the need for an explicit --with in
245 debian/rules that only duplicates what is already declared via the
246 build dependencies in debian/control. The relation can (since
247 12.5) be made optional via e.g. build-profiles. This enables you
248 to easily disable an addon that is only useful with certain
249 profiles (e.g. to facilitate bootstrapping).
250 Since debhelper 12.5, addons can also be activated in indep-only
252 mode (via Build-Depends-Indep) or arch-only mode (via Build-
253 Depends-Arch). Such addons are only active in the particular
254 sequence (e.g. binary-indep) which simplifies dependency management
255 for cross-builds.
256 Please note that addons activated via Build-Depends-Indep or Build-
258 Depends-Arch are subject to additional limitations to ensure the
259 result is deterministic even when the addon is unavailable (e.g.
260 during clean). This implies that some addons are incompatible with
261 these restrictions and can only be used via Build-Depends (or
262 manually via debian/rules). Currently, such addons can only add
263 commands to sequences.
264 --without addon
266 The inverse of --with, disables using the given addon. This option
267 can be repeated more than once, or multiple addons to disable can
268 be listed, separated by commas.
269 --list, -l
271 List all available addons.
272 When called only with this option, dh can be called from any
274 directory (i.e. it does not need access to files from a source
275 package).
276 --no-act
278 Prints commands that would run for a given sequence, but does not
279 run them.
280 Note that dh normally skips running commands that it knows will do
282 nothing. With --no-act, the full list of commands in a sequence is
283 printed.
284 Other options passed to dh are passed on to each command it runs. This
286 can be used to set an option like -v or -X or -N, as well as for more
287 specialised options.
288
290 To see what commands are included in a sequence, without actually doing
291 anything:
292 dh binary-arch --no-act
294 This is a very simple rules file, for packages where the default
296 sequences of commands work with no additional options.
297 #!/usr/bin/make -f
299 %:
300 dh $@
301 Often you'll want to pass an option to a specific debhelper command.
303 The easy way to do with is by adding an override target for that
304 command.
305 #!/usr/bin/make -f
307 %:
308 dh $@
309 override_dh_strip:
311 dh_strip -Xfoo
312 override_dh_auto_configure:
314 dh_auto_configure -- --with-foo --disable-bar
315 Sometimes the automated dh_auto_configure(1) and dh_auto_build(1) can't
317 guess what to do for a strange package. Here's how to avoid running
318 either and instead run your own commands.
319 #!/usr/bin/make -f
321 %:
322 dh $@
323 override_dh_auto_configure:
325 ./mondoconfig
326 override_dh_auto_build:
328 make universe-explode-in-delight
329 Another common case is wanting to do something manually before or after
331 a particular debhelper command is run.
332 #!/usr/bin/make -f
334 %:
335 dh $@
336 # Example assumes debhelper/12.8 and compat 10+
338 execute_after_dh_fixperms:
339 chmod 4755 debian/foo/usr/bin/foo
340 If you are on an older debhelper or compatibility level, the above
342 example would have to be written as.
343 #!/usr/bin/make -f
345 %:
346 dh $@
347 # Older debhelper versions or using compat 9 or lower.
349 override_dh_fixperms:
350 dh_fixperms
351 chmod 4755 debian/foo/usr/bin/foo
352 Python tools are not run by dh by default, due to the continual change
354 in that area. Here is how to use dh_python2.
355 #!/usr/bin/make -f
357 %:
358 dh $@ --with python2
359 Here is how to force use of Perl's Module::Build build system, which
361 can be necessary if debhelper wrongly detects that the package uses
362 MakeMaker.
363 #!/usr/bin/make -f
365 %:
366 dh $@ --buildsystem=perl_build
367 Here is an example of overriding where the dh_auto_* commands find the
369 package's source, for a package where the source is located in a
370 subdirectory.
371 #!/usr/bin/make -f
373 %:
374 dh $@ --sourcedirectory=src
375 And here is an example of how to tell the dh_auto_* commands to build
377 in a subdirectory, which will be removed on clean.
378 #!/usr/bin/make -f
380 %:
381 dh $@ --builddirectory=build
382 If your package can be built in parallel, please either use compat 10
384 or pass --parallel to dh. Then dpkg-buildpackage -j will work.
385 #!/usr/bin/make -f
387 %:
388 dh $@ --parallel
389 If your package cannot be built reliably while using multiple threads,
391 please pass --no-parallel to dh (or the relevant dh_auto_* command):
392 #!/usr/bin/make -f
394 %:
395 dh $@ --no-parallel
396 Here is a way to prevent dh from running several commands that you
398 don't want it to run, by defining empty override targets for each
399 command.
400 #!/usr/bin/make -f
402 %:
403 dh $@
404 # Commands not to run:
406 override_dh_auto_test override_dh_compress override_dh_fixperms:
407 A long build process for a separate documentation package can be
409 separated out using architecture independent overrides. These will be
410 skipped when running build-arch and binary-arch sequences.
411 #!/usr/bin/make -f
413 %:
414 dh $@
415 override_dh_auto_build-indep:
417 $(MAKE) -C docs
418 # No tests needed for docs
420 override_dh_auto_test-indep:
421 override_dh_auto_install-indep:
423 $(MAKE) -C docs install
424 Adding to the example above, suppose you need to chmod a file, but only
426 when building the architecture dependent package, as it's not present
427 when building only documentation.
428 # Example assumes debhelper/12.8 and compat 10+
430 execute_after_dh_fixperms-arch:
431 chmod 4755 debian/foo/usr/bin/foo
432
434 The primary purpose of dh addons is to provide easy integration with
435 third-party provided features for debhelper. However, debhelper itself
436 also provide a few sequences that can be useful in some cases. These
437 are documented in this list:
438 build-stamp
440 A special addon for controlling whether dh (in compat 10 or later)
441 will create stamp files to tell whether the build target has been
442 run successfully. See "INTERNALS" for more details.
443 This addon is active by default but can disabled by using dh $@
445 --without build-stamp
446 dwz (obsolete)
448 Adds dh_dwz(1) to the sequence in compat level 11 or below.
449 Obsolete in compat 12 or later.
450 elf-tools
452 This addon adds tools related to ELF files to the sequence such as
453 dh_strip(1) and dh_shlibdeps(1)
454 This addon is conditionally active by default for architecture
456 specific packages - that is, it is skipped for arch:all packages.
457 In the special case where you need these tools to work on arch:all
458 packages, you can use --with elf-tools to activate it
459 unconditionally.
460 installinitramfs (obsolete)
462 Adds dh_installinitramfs(1) to the sequence in compat level 11 or
463 below. Obsolete in compat 12 or later.
464 root-sequence (internal)
466 This is reserved for internal usage.
467 single-binary
469 A special-purpose addon that makes debhelper run in "single binary"
470 mode.
471 When active, it will pass --destdir=debian/package/ to
473 dh_auto_install(1). This makes every file "installed" by the
474 upstream build system part of the (only) binary package by default
475 without having to use other helpers such as dh_install(1).
476 The addon will refuse to activate when the source package lists 2
478 or more binary packages in debian/control as a precaution.
479 Before compat 15. this behaviour was the default when there was
481 only a single binary package listed in debian/control. In compat
482 15 and later, this addon must explicitly be activated for this
483 feature to work.
484 The rationale for requiring this as an explicit choice is that if
486 it is implicit then debhelper will silently change behaviour on
487 adding a new binary package. This has caused many RC bugs when
488 maintainers renamed a binary and added transitional packages with
489 the intention of supporting seamless upgrades. The result would
490 often be two empty binary packages that were uploaded to archive
491 with users frustrated as their "upgrade" removed their programs.
492 systemd (obsolete)
494 Adds dh_systemd_enable(1) and dh_systemd_start(1) to the sequence
495 in compat level 10 or below. Obsolete in compat 11 or later.
496
498 If you're curious about dh's internals, here's how it works under the
499 hood.
500 In compat 10 (or later), dh creates a stamp file
502 debian/debhelper-build-stamp after the build step(s) are complete to
503 avoid re-running them. It is possible to avoid the stamp file by
504 passing --without=build-stamp to dh. This makes "no clean" builds
505 behave more like what some people expect at the expense of possibly
506 running the build and test twice (the second time as root or under
507 fakeroot(1)).
508 Inside an override target, dh_* commands will create a log file
510 debian/package.debhelper.log to keep track of which packages the
511 command(s) have been run for. These log files are then removed once
512 the override target is complete.
513 In compat 9 or earlier, each debhelper command will record when it's
515 successfully run in debian/package.debhelper.log. (Which dh_clean
516 deletes.) So dh can tell which commands have already been run, for
517 which packages, and skip running those commands again.
518 Each time dh is run (in compat 9 or earlier), it examines the log, and
520 finds the last logged command that is in the specified sequence. It
521 then continues with the next command in the sequence.
522 A sequence can also run dependent targets in debian/rules. For
524 example, the "binary" sequence runs the "install" target.
525 dh uses the DH_INTERNAL_OPTIONS environment variable to pass
527 information through to debhelper commands that are run inside override
528 targets. The contents (and indeed, existence) of this environment
529 variable, as the name might suggest, is subject to change at any time.
530 Commands in the build-indep, install-indep and binary-indep sequences
532 are passed the -i option to ensure they only work on architecture
533 independent packages, and commands in the build-arch, install-arch and
534 binary-arch sequences are passed the -a option to ensure they only work
535 on architecture dependent packages.
536
538 debhelper(7)
539 This program is a part of debhelper.
541
543 Joey Hess <joeyh@debian.org>
54413.11.4 2023-01-22 DH(1)