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_after_dh_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 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
59       Note that the target has to be completely empty for this to work:
60
61            # Skip dh_bar - the good and optimized way
62            # Some rationale for skipping dh_bar goes here
63            override_dh_bar:
64
65
66            # 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
71   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
76           $ 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
97       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
102       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
106       If you are interested in the other attributes, please read the
107       dh_assistant(1) for the details.
108
109       Verifying targets are picked up by dh (when debhelper is older than
110       13.10)
111
112       On older versions of debhelper, you have to use dh with --no-act.  You
113       can use the following command as an example:
114
115           $ 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
122       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
126       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
131   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
138       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
143       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
147             # 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
161             # 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
175
176             # 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
190       These recipes are also relevant for conditional dependency targets,
191       which are often seen in a variant of the following example:
192
193             COND_TASKS =
194             ifneq (...)
195             COND_TASKS += maybe-run-this
196             endif
197             ...
198
199             maybe-run-this:
200                 ...
201
202             # 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
212
213             # 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
224             # 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
231       When in doubt, pick the relevant SIMPLE case in the examples above that
232       match your need.
233

OPTIONS

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
243           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
251           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
257           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
265       --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
270       --list, -l
271           List all available addons.
272
273           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
277       --no-act
278           Prints commands that would run for a given sequence, but does not
279           run them.
280
281           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
285       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

EXAMPLES

290       To see what commands are included in a sequence, without actually doing
291       anything:
292
293               dh binary-arch --no-act
294
295       This is a very simple rules file, for packages where the default
296       sequences of commands work with no additional options.
297
298               #!/usr/bin/make -f
299               %:
300                       dh $@
301
302       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
306               #!/usr/bin/make -f
307               %:
308                       dh $@
309
310               override_dh_strip:
311                       dh_strip -Xfoo
312
313               override_dh_auto_configure:
314                       dh_auto_configure -- --with-foo --disable-bar
315
316       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
320               #!/usr/bin/make -f
321               %:
322                       dh $@
323
324               override_dh_auto_configure:
325                       ./mondoconfig
326
327               override_dh_auto_build:
328                       make universe-explode-in-delight
329
330       Another common case is wanting to do something manually before or after
331       a particular debhelper command is run.
332
333               #!/usr/bin/make -f
334               %:
335                       dh $@
336
337               # Example assumes debhelper/12.8 and compat 10+
338               execute_after_dh_fixperms:
339                       chmod 4755 debian/foo/usr/bin/foo
340
341       If you are on an older debhelper or compatibility level, the above
342       example would have to be written as.
343
344               #!/usr/bin/make -f
345               %:
346                       dh $@
347
348               # 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
353       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
356               #!/usr/bin/make -f
357               %:
358                       dh $@ --with python2
359
360       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
364               #!/usr/bin/make -f
365               %:
366                       dh $@ --buildsystem=perl_build
367
368       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
372               #!/usr/bin/make -f
373               %:
374                       dh $@ --sourcedirectory=src
375
376       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
379               #!/usr/bin/make -f
380               %:
381                       dh $@ --builddirectory=build
382
383       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
386               #!/usr/bin/make -f
387               %:
388                       dh $@ --parallel
389
390       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
393               #!/usr/bin/make -f
394               %:
395                       dh $@ --no-parallel
396
397       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
401               #!/usr/bin/make -f
402               %:
403                       dh $@
404
405               # Commands not to run:
406               override_dh_auto_test override_dh_compress override_dh_fixperms:
407
408       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
412               #!/usr/bin/make -f
413               %:
414                       dh $@
415
416               override_dh_auto_build-indep:
417                       $(MAKE) -C docs
418
419               # No tests needed for docs
420               override_dh_auto_test-indep:
421
422               override_dh_auto_install-indep:
423                       $(MAKE) -C docs install
424
425       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
429               # Example assumes debhelper/12.8 and compat 10+
430               execute_after_dh_fixperms-arch:
431                       chmod 4755 debian/foo/usr/bin/foo
432

DEBHELPER PROVIDED DH ADDONS

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
439       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
444           This addon is active by default but can disabled by using dh $@
445           --without build-stamp
446
447       dwz (obsolete)
448           Adds dh_dwz(1) to the sequence in compat level 11 or below.
449           Obsolete in compat 12 or later.
450
451       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
455           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
461       installinitramfs (obsolete)
462           Adds dh_installinitramfs(1) to the sequence in compat level 11 or
463           below.  Obsolete in compat 12 or later.
464
465       root-sequence (internal)
466           This is reserved for internal usage.
467
468       single-binary
469           A special-purpose addon that makes debhelper run in "single binary"
470           mode.
471
472           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
477           The addon will refuse to activate when the source package lists 2
478           or more binary packages in debian/control as a precaution.
479
480           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
485           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
493       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

INTERNALS

498       If you're curious about dh's internals, here's how it works under the
499       hood.
500
501       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
509       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
514       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
519       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
523       A sequence can also run dependent targets in debian/rules.  For
524       example, the "binary" sequence runs the "install" target.
525
526       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
531       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

SEE ALSO

538       debhelper(7)
539
540       This program is a part of debhelper.
541

AUTHOR

543       Joey Hess <joeyh@debian.org>
544
545
546
54713.11.6                           2023-09-02                             DH(1)
Impressum