1debhelper(7)                       Debhelper                      debhelper(7)
2
3
4

NAME

6       debhelper - the debhelper tool suite
7

SYNOPSIS

9       dh_* [-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]
10

DESCRIPTION

12       Debhelper is used to help you build a Debian package. The philosophy
13       behind debhelper is to provide a collection of small, simple, and
14       easily understood tools that are used in debian/rules to automate
15       various common aspects of building a package. This means less work for
16       you, the packager.  It also, to some degree means that these tools can
17       be changed if Debian policy changes, and packages that use them will
18       require only a rebuild to comply with the new policy.
19
20       A typical debian/rules file that uses debhelper will call several
21       debhelper commands in sequence, or use dh(1) to automate this process.
22       Examples of rules files that use debhelper are in
23       /usr/share/doc/debhelper/examples/
24
25       To create a new Debian package using debhelper, you can just copy one
26       of the sample rules files and edit it by hand. Or you can try the dh-
27       make package, which contains a dh_make command that partially automates
28       the process. For a more gentle introduction, the maint-guide Debian
29       package contains a tutorial about making your first package using
30       debhelper.
31
32       Except where the tool explicitly denotes otherwise, all of the
33       debhelper tools assume that they run from the root directory of an
34       unpacked source package.  This is so they can locate find files like
35       debian/control when needed.
36

DEBHELPER COMMANDS

38       Here is the list of debhelper commands you can use. See their man pages
39       for additional documentation.
40
41       dh_assistant(1)
42           tool for supporting debhelper tools and provide introspection
43
44       dh_auto_build(1)
45           automatically builds a package
46
47       dh_auto_clean(1)
48           automatically cleans up after a build
49
50       dh_auto_configure(1)
51           automatically configure a package prior to building
52
53       dh_auto_install(1)
54           automatically runs make install or similar
55
56       dh_auto_test(1)
57           automatically runs a package's test suites
58
59       dh_bugfiles(1)
60           install bug reporting customization files into package build
61           directories
62
63       dh_builddeb(1)
64           build Debian binary packages
65
66       dh_clean(1)
67           clean up package build directories
68
69       dh_compress(1)
70           compress files and fix symlinks in package build directories
71
72       dh_dwz(1)
73           optimize DWARF debug information in ELF binaries via dwz
74
75       dh_fixperms(1)
76           fix permissions of files in package build directories
77
78       dh_gencontrol(1)
79           generate and install control file
80
81       dh_icons(1)
82           Update caches of Freedesktop icons
83
84       dh_install(1)
85           install files into package build directories
86
87       dh_installalternatives(1)
88           install declarative alternative rules
89
90       dh_installcatalogs(1)
91           install and register SGML Catalogs
92
93       dh_installchangelogs(1)
94           install changelogs into package build directories
95
96       dh_installcron(1)
97           install cron scripts into etc/cron.*
98
99       dh_installdeb(1)
100           install files into the DEBIAN directory
101
102       dh_installdebconf(1)
103           install files used by debconf in package build directories
104
105       dh_installdirs(1)
106           create subdirectories in package build directories
107
108       dh_installdocs(1)
109           install documentation into package build directories
110
111       dh_installemacsen(1)
112           register an Emacs add on package
113
114       dh_installexamples(1)
115           install example files into package build directories
116
117       dh_installgsettings(1)
118           install GSettings overrides and set dependencies
119
120       dh_installifupdown(1)
121           install if-up and if-down hooks
122
123       dh_installinfo(1)
124           install info files
125
126       dh_installinit(1)
127           install service init files into package build directories
128
129       dh_installinitramfs(1)
130           install initramfs hooks and setup maintscripts
131
132       dh_installlogcheck(1)
133           install logcheck rulefiles into etc/logcheck/
134
135       dh_installlogrotate(1)
136           install logrotate config files
137
138       dh_installman(1)
139           install man pages into package build directories
140
141       dh_installmenu(1)
142           install Debian menu files into package build directories
143
144       dh_installmime(1)
145           install mime files into package build directories
146
147       dh_installmodules(1)
148           register kernel modules
149
150       dh_installpam(1)
151           install pam support files
152
153       dh_installppp(1)
154           install ppp ip-up and ip-down files
155
156       dh_installsystemd(1)
157           install systemd unit files
158
159       dh_installsystemduser(1)
160           install systemd unit files
161
162       dh_installsysusers(1)
163           install and integrates systemd sysusers files
164
165       dh_installtmpfiles(1)
166           install tmpfiles.d configuration files
167
168       dh_installudev(1)
169           install udev rules files
170
171       dh_installwm(1)
172           register a window manager
173
174       dh_installxfonts(1)
175           register X fonts
176
177       dh_link(1)
178           create symlinks in package build directories
179
180       dh_lintian(1)
181           install lintian override files into package build directories
182
183       dh_listpackages(1)
184           list binary packages debhelper will act on
185
186       dh_makeshlibs(1)
187           automatically create shlibs file and call dpkg-gensymbols
188
189       dh_md5sums(1)
190           generate DEBIAN/md5sums file
191
192       dh_missing(1)
193           check for missing files
194
195       dh_movefiles(1)
196           move files out of debian/tmp into subpackages
197
198       dh_perl(1)
199           calculates Perl dependencies and cleans up after MakeMaker
200
201       dh_prep(1)
202           perform cleanups in preparation for building a binary package
203
204       dh_shlibdeps(1)
205           calculate shared library dependencies
206
207       dh_strip(1)
208           strip executables, shared libraries, and some static libraries
209
210       dh_systemd_enable(1)
211           enable/disable systemd unit files
212
213       dh_systemd_start(1)
214           start/stop/restart systemd unit files
215
216       dh_testdir(1)
217           test directory before building Debian package
218
219       dh_testroot(1)
220           ensure that a package is built with necessary level of root
221           permissions
222
223       dh_ucf(1)
224           register configuration files with ucf
225
226       dh_update_autotools_config(1)
227           Update autotools config files
228
229       dh_usrlocal(1)
230           migrate usr/local directories to maintainer scripts
231
232   Deprecated Commands
233       A few debhelper commands are deprecated and should not be used.
234
235       dh_installmanpages(1)
236           old-style man page installer (deprecated)
237
238   Other Commands
239       If a program's name starts with dh_, and the program is not on the
240       above lists, then it is not part of the debhelper package, but it
241       should still work like the other programs described on this page.
242

DEBHELPER CONFIG FILES

244       Many debhelper commands make use of files in debian/ to control what
245       they do. Besides the common debian/changelog and debian/control, which
246       are in all packages, not just those using debhelper, some additional
247       files can be used to configure the behavior of specific debhelper
248       commands. These files are typically named debian/package.foo (where
249       package of course, is replaced with the package that is being acted
250       on).
251
252       For example, dh_installdocs uses files named debian/package.docs to
253       list the documentation files it will install. See the man pages of
254       individual commands for details about the names and formats of the
255       files they use.  Generally, these files will list files to act on, one
256       file per line. Some programs in debhelper use pairs of files and
257       destinations or slightly more complicated formats.
258
259       Note for the first (or only) binary package listed in debian/control,
260       debhelper will use debian/foo when there's no debian/package.foo file.
261       However, it is often a good idea to keep the package. prefix as it is
262       more explicit.  The primary exception to this are files that debhelper
263       by default installs in every binary package when it does not have a
264       package prefix (such as debian/copyright or debian/changelog).
265
266       In some rare cases, you may want to have different versions of these
267       files for different architectures or OSes. If files named
268       debian/package.foo.ARCH or debian/package.foo.OS exist, where ARCH and
269       OS are the same as the output of "dpkg-architecture -qDEB_HOST_ARCH" /
270       "dpkg-architecture -qDEB_HOST_ARCH_OS", then they will be used in
271       preference to other, more general files.
272
273       Mostly, these config files are used to specify lists of various types
274       of files. Documentation or example files to install, files to move, and
275       so on.  When appropriate, in cases like these, you can use standard
276       shell wildcard characters (? and * and [..] character classes) in the
277       files.  You can also put comments in these files; lines beginning with
278       # are ignored.
279
280       The syntax of these files is intentionally kept very simple to make
281       them easy to read, understand, and modify.
282
283   Substitutions in debhelper config files
284       In compatibility level 13 and later, it is possible to use simple
285       substitutions in debhelper config files for the following tools:
286
287       •   dh_clean
288
289       •   dh_install
290
291       •   dh_installcatalogs
292
293       •   dh_installdeb
294
295       •   dh_installdirs
296
297       •   dh_installdocs
298
299       •   dh_installexamples
300
301       •   dh_installinfo
302
303       •   dh_installman
304
305       •   dh_installwm
306
307       •   dh_link
308
309       •   dh_missing
310
311       •   dh_ucf
312
313       All substitution variables are of the form ${foo} and the braces are
314       mandatory.  Variable names are case-sensitive and consist of
315       alphanumerics (a-zA-Z0-9), hyphens (-), underscores (_), and colons
316       (:).  The first character must be an alphanumeric.
317
318       If you need a literal dollar sign that cannot trigger a substitution,
319       you can either use the ${Dollar} substitution or the sequence ${}.
320
321       The following expansions are available:
322
323       DEB_HOST_*, DEB_BUILD_*, DEB_TARGET_*
324           Expands to the relevant dpkg-architecture(1) value (similar to
325           dpkg-architecture -qVARIABLE_HERE).
326
327           When in doubt, the DEB_HOST_* variant is the one that will work
328           both for native and cross builds.
329
330           For performance reasons, debhelper will attempt to resolve these
331           names from the environment first before consulting
332           dpkg-architecture(1).  This is mostly mentioned for completeness as
333           it will not matter for most cases.
334
335       Dollar
336           Expands to a single literal $-symbol.  This symbol will never be
337           considered part of a substitution variable.  That is:
338
339              # Triggers an error
340              ${NO_SUCH_TOKEN}
341              # Expands to the literal value "${NO_SUCH_TOKEN}"
342              ${Dollar}{NO_SUCH_TOKEN}
343
344           This variable equivalent to the sequence ${} and the two can be
345           used interchangeably.
346
347       Newline, Space, Tab
348           Expands to a single ASCII newline, space and tab respectively.
349
350           This can be useful if you need to include a literal whitespace
351           character (e.g. space) where it would otherwise be stripped or used
352           as a separator.
353
354       env:NAME
355           Expands to the environment variable NAME.  The environment variable
356           must be set (but can be set to the empty string).
357
358       Note that all variables must expand to a defined value.  As an example,
359       if debhelper sees ${env:FOO}, then it will insist that the environment
360       variable FOO is set (it can be set to the empty string).
361
362       Substitution limits
363
364       To avoid infinite loops and resource exhaustion, debhelper will stop
365       with an error if the text contains many substitution variables (50) or
366       they expand beyond a certain size (4096 characters or 3x length of the
367       original input - whichever is bigger).
368
369   Executable debhelper config files
370       If you need additional flexibility, many of the debhelper tools (e.g.
371       dh_install(1)) support executing a config file as a script.
372
373       To use this feature, simply mark the config file as executable (e.g.
374       chmod +x debian/package.install) and the tool will attempt to execute
375       it and use the output of the script.  In many cases, you can use
376       dh-exec(1) as interpreter of the config file to retain most of the
377       original syntax while getting the additional flexibility you need.
378
379       When using executable debhelper config files, please be aware of the
380       following:
381
382       •   The executable config file must exit with success (i.e. its return
383           code should indicate success).
384
385       •   In compatibility level 13+, the output will be subject to
386           substitutions (see "Substitutions in debhelper config files") where
387           the tool support these.  Remember to be careful if your generator
388           also provides substitutions as this can cause unnecessary
389           confusion.
390
391           Otherwise, the output will be used exactly as-is.  Notably,
392           debhelper will not expand wildcards or strip comments or strip
393           whitespace in the output.
394
395       If you need the package to build on a file system where you cannot
396       disable the executable bit, then you can use dh-exec(1) and its strip-
397       output script.
398

SHARED DEBHELPER OPTIONS

400       The following command line options are supported by all debhelper
401       programs.
402
403       -v, --verbose
404           Verbose mode: show all commands that modify the package build
405           directory.
406
407       --no-act
408           Do not really do anything. If used with -v, the result is that the
409           command will output what it would have done.
410
411       -a, --arch
412           Act on architecture dependent packages that should be built for the
413           DEB_HOST_ARCH architecture.
414
415       -i, --indep
416           Act on all architecture independent packages.
417
418       -ppackage, --package=package
419           Act on the package named package. This option may be specified
420           multiple times to make debhelper operate on a given set of
421           packages.
422
423       -s, --same-arch
424           Deprecated alias of -a.
425
426           This option is removed in compat 12.
427
428       -Npackage, --no-package=package
429           Do not act on the specified package even if an -a, -i, or -p option
430           lists the package as one that should be acted on.
431
432       --remaining-packages
433           Do not act on the packages which have already been acted on by this
434           debhelper command earlier (i.e. if the command is present in the
435           package debhelper log).  For example, if you need to call the
436           command with special options only for a couple of binary packages,
437           pass this option to the last call of the command to process the
438           rest of packages with default settings.
439
440       -Ptmpdir, --tmpdir=tmpdir
441           Use tmpdir for package build directory. The default is
442           debian/package
443
444       --mainpackage=package
445           This little-used option changes the package which debhelper
446           considers the "main package", that is, the first one listed in
447           debian/control, and the one for which debian/foo files can be used
448           instead of the usual debian/package.foo files.
449
450       -O=option|bundle
451           This is used by dh(1) when passing user-specified options to all
452           the commands it runs. If the command supports the specified option
453           or option bundle, it will take effect. If the command does not
454           support the option (or any part of an option bundle), it will be
455           ignored.
456

COMMON DEBHELPER OPTIONS

458       The following command line options are supported by some debhelper
459       programs.  See the man page of each program for a complete explanation
460       of what each option does.
461
462       -n  Do not modify postinst, postrm, etc. scripts.
463
464       -Xitem, --exclude=item
465           Exclude an item from processing. This option may be used multiple
466           times, to exclude more than one thing. The item is typically part
467           of a filename, and any file containing the specified text will be
468           excluded.
469
470       -A, --all
471           Makes files or other items that are specified on the command line
472           take effect in ALL packages acted on, not just the first.
473

BUILD SYSTEM OPTIONS

475       The following command line options are supported by all of the
476       dh_auto_* debhelper programs. These programs support a variety of build
477       systems, and normally heuristically determine which to use, and how to
478       use them.  You can use these command line options to override the
479       default behavior.  Typically these are passed to dh(1), which then
480       passes them to all the dh_auto_* programs.
481
482       -Sbuildsystem, --buildsystem=buildsystem
483           Force use of the specified buildsystem, instead of trying to auto-
484           select one which might be applicable for the package.
485
486           Pass none as buildsystem to disable auto-selection.
487
488       -Ddirectory, --sourcedir=directory, --sourcedirectory=directory
489           Assume that the original package source tree is at the specified
490           directory rather than the top level directory of the Debian source
491           package tree.
492
493           Warning: The --sourcedir variant matches a similar named option in
494           dh_install and dh_missing (etc.) for historical reasons.  While
495           they have a similar name, they have very distinct purposes and in
496           some cases it can cause errors when this variant is passed to dh
497           (when then passes it on to all tools).
498
499       -B[directory], --builddir[=directory], --builddirectory[=directory]
500           Enable out of source building and use the specified directory as
501           the build directory. If directory parameter is omitted, a default
502           build directory will be chosen.
503
504           If this option is not specified, building will be done in source by
505           default unless the build system requires or prefers out of source
506           tree building.  In such a case, the default build directory will be
507           used even if --builddirectory is not specified.
508
509           If the build system prefers out of source tree building but still
510           allows in source building, the latter can be re-enabled by passing
511           a build directory path that is the same as the source directory
512           path.
513
514       --parallel, --no-parallel
515           Control whether parallel builds should be used if underlying build
516           system supports them.  The number of parallel jobs is controlled by
517           the DEB_BUILD_OPTIONS environment variable ("Debian Policy, section
518           4.9.1") at build time. It might also be subject to a build system
519           specific limit.
520
521           If neither option is specified, debhelper currently defaults to
522           --parallel in compat 10 (or later) and --no-parallel otherwise.
523
524           As an optimization, dh will try to avoid passing these options to
525           subprocesses, if they are unnecessary and the only options passed.
526           Notably this happens when DEB_BUILD_OPTIONS does not have a
527           parallel parameter (or its value is 1).
528
529       --max-parallel=maximum
530           This option implies --parallel and allows further limiting the
531           number of jobs that can be used in a parallel build. If the package
532           build is known to only work with certain levels of concurrency, you
533           can set this to the maximum level that is known to work, or that
534           you wish to support.
535
536           Notably, setting the maximum to 1 is effectively the same as using
537           --no-parallel.
538
539       --reload-all-buildenv-variables
540           By default, dh(1) will compute several environment (e.g. by using
541           dpkg-buildflags(1)) and cache them to avoid having all dh_auto_*
542           tool recompute them.
543
544           When passing this option, the concrete dh_auto_* tool will ignore
545           the cache from dh(1) and retrigger a rebuild of these variables.
546           This is useful in the very rare case where the package need to do
547           multiple builds but with different ...FLAGS options.  A concrete
548           example would be needing to change the -O parameter in CFLAGS in
549           the second build:
550
551               export DEB_CFLAGS_MAINT_APPEND=-O3
552
553               %:
554                   dh $@
555
556               override_dh_auto_configure:
557                   dh_auto_configure -Bbuild-deb ...
558                   DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
559                      --reload-all-buildenv-variables -Bbuild-udeb ...
560
561           Without --reload-all-buildenv-variables in the second call to
562           dh_auto_configure(1), the change in DEB_CFLAGS_MAINT_APPEND would
563           be ignored as dh_auto_configure(1) would use the cached value of
564           CFLAGS set by dh(1).
565
566           This option is only available with debhelper (>= 12.7~) when the
567           package uses compatibility level 9 or later.
568
569       --list, -l
570           List all build systems supported by debhelper on this system. The
571           list includes both default and third party build systems (marked as
572           such). Also shows which build system would be automatically
573           selected, or which one is manually specified with the --buildsystem
574           option.
575

COMPATIBILITY LEVELS

577       From time to time, major non-backwards-compatible changes need to be
578       made to debhelper, to keep it clean and well-designed as needs change
579       and its author gains more experience. To prevent such major changes
580       from breaking existing packages, the concept of debhelper compatibility
581       levels was introduced. You must tell debhelper which compatibility
582       level it should use, and it modifies its behavior in various ways.
583
584       In current debhelper, you can specify the compatibility level in
585       debian/control by adding a Build-Depends on the debhelper-compat
586       package.  For example, to use v13 mode, ensure debian/control has:
587
588         Build-Depends: debhelper-compat (= 13)
589
590       This also serves as an appropriate versioned build dependency on a
591       sufficient version of the debhelper package, so you do not need to
592       specify a separate versioned build dependency on the debhelper package
593       unless you need a specific point release of debhelper (such as for the
594       introduction of a new feature or bugfix within a compatibility level).
595
596       Note that debhelper does not provide debhelper-compat for experimental
597       or beta compatibility levels; packages experimenting with those
598       compatibility levels should use debian/compat or DH_COMPAT.
599
600       Prior versions of debhelper required specifying the compatibility level
601       in the file debian/compat, and current debhelper still supports this
602       for backward compatibility, though a package may not specify a
603       compatibility level via multiple methods at once. To use this method,
604       debian/compat should contain the compatibility level as a single
605       number, and no other content. If you specify the compatibility level by
606       this method, your package will also need a versioned build dependency
607       on a version of the debhelper package equal to (or greater than) the
608       compatibility level your package uses. So, if you specify compatibility
609       level 13 in debian/compat, ensure debian/control has:
610
611         Build-Depends: debhelper (>= 13~)
612
613       Unless otherwise indicated, all debhelper documentation assumes that
614       you are using the most recent compatibility level, and in most cases
615       does not indicate if the behavior is different in an earlier
616       compatibility level, so if you are not using the most recent
617       compatibility level, you're advised to read below for notes about what
618       is different in earlier compatibility levels.
619
620   Supported compatibility levels
621       These are the available compatibility levels:
622
623       v5  This is the lowest supported compatibility level.
624
625           If you are upgrading from an earlier compatibility level, please
626           review debhelper-obsolete-compat(7).
627
628           This mode is deprecated.
629
630       v6  Changes from v5 are:
631
632           -       Commands that generate maintainer script fragments will
633                   order the fragments in reverse order for the prerm and
634                   postrm scripts.
635
636           -       dh_installwm will install a slave manpage link for
637                   x-window-manager.1.gz, if it sees the man page in
638                   usr/share/man/man1 in the package build directory.
639
640           -       dh_builddeb did not previously delete everything matching
641                   DH_ALWAYS_EXCLUDE, if it was set to a list of things to
642                   exclude, such as CVS:.svn:.git. Now it does.
643
644           -       dh_installman allows overwriting existing man pages in the
645                   package build directory. In previous compatibility levels
646                   it silently refuses to do this.
647
648           This mode is deprecated.
649
650       v7  Changes from v6 are:
651
652           -       dh_install, will fall back to looking for files in
653                   debian/tmp if it doesn't find them in the current directory
654                   (or wherever you tell it look using --sourcedir). This
655                   allows dh_install to interoperate with dh_auto_install,
656                   which installs to debian/tmp, without needing any special
657                   parameters.
658
659           -       dh_clean will read debian/clean and delete files listed
660                   there.
661
662           -       dh_clean will delete toplevel *-stamp files.
663
664           -       dh_installchangelogs will guess at what file is the
665                   upstream changelog if none is specified.
666
667           This mode is deprecated.
668
669       v8  Changes from v7 are:
670
671           -       Commands will fail rather than warning when they are passed
672                   unknown options.
673
674           -       dh_makeshlibs will run dpkg-gensymbols on all shared
675                   libraries that it generates shlibs files for. So -X can be
676                   used to exclude libraries.  Also, libraries in unusual
677                   locations that dpkg-gensymbols would not have processed
678                   before will be passed to it, a behavior change that can
679                   cause some packages to fail to build.
680
681           -       dh requires the sequence to run be specified as the first
682                   parameter, and any switches come after it. Ie, use "dh $@
683                   --foo", not "dh --foo $@".
684
685           -       dh_auto_* prefer to use Perl's Module::Build in preference
686                   to Makefile.PL.
687
688           This mode is deprecated.
689
690       v9  Changes from v8 are:
691
692           -       Multiarch support. In particular, dh_auto_configure passes
693                   multiarch directories to autoconf in --libdir and
694                   --libexecdir.
695
696           -       dh is aware of the usual dependencies between targets in
697                   debian/rules.  So, "dh binary" will run any build, build-
698                   arch, build-indep, install, etc targets that exist in the
699                   rules file. There's no need to define an explicit binary
700                   target with explicit dependencies on the other targets.
701
702           -       dh_strip compresses debugging symbol files to reduce the
703                   installed size of -dbg packages.
704
705           -       dh_auto_configure does not include the source package name
706                   in --libexecdir when using autoconf.
707
708           -       dh does not default to enabling --with=python-support
709
710                   (Obsolete: As the dh_pysupport tool was removed from Debian
711                   stretch.  Since debhelper/10.3, dh no longer enables this
712                   sequence add-on regardless of compat level)
713
714           -       All of the dh_auto_* debhelper programs and dh set
715                   environment variables listed by dpkg-buildflags, unless
716                   they are already set.
717
718           -       dh_auto_configure passes dpkg-buildflags CFLAGS, CPPFLAGS,
719                   and LDFLAGS to perl Makefile.PL and Build.PL
720
721           -       dh_strip puts separated debug symbols in a location based
722                   on their build-id.
723
724           -       Executable debhelper config files are run and their output
725                   used as the configuration.
726
727           This mode is deprecated.
728
729       v10 Changes from v9 are:
730
731           -       dh_installinit will no longer install a file named
732                   debian/package as an init script.
733
734           -       dh_installdocs will error out if it detects links created
735                   with --link-doc between packages of architecture "all" and
736                   non-"all" as it breaks binNMUs.
737
738           -       dh_installdeb no longer installs a maintainer-provided
739                   debian/package.shlibs file.  This is now done by
740                   dh_makeshlibs instead.
741
742           -       dh_installwm refuses to create a broken package if no man
743                   page can be found (required to register for the x-window-
744                   manager alternative).
745
746           -       Debhelper will default to --parallel for all buildsystems
747                   that support parallel building.  This can be disabled by
748                   using either --no-parallel or passing --max-parallel with a
749                   value of 1.
750
751           -       The dh command will not accept any of the deprecated
752                   "manual sequence control" parameters (--before, --after,
753                   etc.).  Please use override targets instead.
754
755                   Retroactively applied to earlier compat levels: dh no
756                   longer accepts any of these since debhelper/12.4.
757
758           -       The dh command will no longer use log files to track which
759                   commands have been run.  The dh command still keeps track
760                   of whether it already ran the "build" sequence and skip it
761                   if it did.
762
763                   The main effects of this are:
764
765                   -   With this, it is now easier to debug the install or/and
766                       binary sequences because they can now trivially be re-
767                       run (without having to do a full "clean and rebuild"
768                       cycle)
769
770                   -   The main caveat is that dh_* now only keeps track of
771                       what happened in a single override target.  When all
772                       the calls to a given dh_cmd command happens in the same
773                       override target everything will work as before.
774
775                       Example of where it can go wrong:
776
777                         override_dh_foo:
778                           dh_foo -pmy-pkg
779
780                         override_dh_bar:
781                           dh_bar
782                           dh_foo --remaining
783
784                       In this case, the call to dh_foo --remaining will also
785                       include my-pkg, since dh_foo -pmy-pkg was run in a
786                       separate override target.  This issue is not limited to
787                       --remaining, but also includes -a, -i, etc.
788
789           -       The dh_installdeb command now shell-escapes the lines in
790                   the maintscript config file.  This was the original intent
791                   but it did not work properly and packages have begun to
792                   rely on the incomplete shell escaping (e.g. quoting file
793                   names).
794
795           -       The dh_installinit command now defaults to
796                   --restart-after-upgrade.  For packages needing the previous
797                   behaviour, please use --no-restart-after-upgrade.
798
799           -       The autoreconf sequence is now enabled by default.  Please
800                   pass --without autoreconf to dh if this is not desirable
801                   for a given package
802
803           -       The systemd sequence is now enabled by default.  Please
804                   pass --without systemd to dh if this is not desirable for a
805                   given package.
806
807           -       Retroactively removed: dh no longer creates the package
808                   build directory when skipping running debhelper commands.
809                   This will not affect packages that only build with
810                   debhelper commands, but it may expose bugs in commands not
811                   included in debhelper.
812
813                   This compatibility feature had a bug since its inception in
814                   debhelper/9.20130516 that made it fail to apply in compat 9
815                   and earlier.  As there has been no reports of issues caused
816                   by this bug in those ~5 years, this item have been removed
817                   rather than fixed.
818
819       v11 This mode is discouraged.
820
821           The compat 11 is discouraged for new packages as it suffers from
822           feature interaction between dh_installinit and dh_installsystemd
823           causing services to not run correctly in some cases.  Please
824           consider using compatibility mode 10 or 12 instead.  More details
825           about the issue are available in Debian#887904 and
826           <https://lists.debian.org/debian-release/2019/04/msg01442.html>.
827
828           Changes from v10 are:
829
830           -       dh_installinit no longer installs service or tmpfile files,
831                   nor generates maintainer scripts for those files.  Please
832                   use the new dh_installsystemd helper.
833
834           -       The dh_systemd_enable and dh_systemd_start helpers have
835                   been replaced by the new dh_installsystemd helper.  For the
836                   same reason, the systemd sequence for dh has also been
837                   removed.  If you need to disable the dh_installsystemd
838                   helper tool, please use an empty override target.
839
840                   Please note that the dh_installsystemd tool has a slightly
841                   different behaviour in some cases (e.g. when using the
842                   --name parameter).
843
844           -       dh_installdirs no longer creates debian/package directories
845                   unless explicitly requested (or it has to create a
846                   subdirectory in it).
847
848                   The vast majority of all packages will be unaffected by
849                   this change.
850
851           -       The makefile buildsystem now passes INSTALL="install
852                   --strip-program=true" to make(1).  Derivative buildsystems
853                   (e.g. configure or cmake) are unaffected by this change.
854
855           -       The autoconf buildsystem now passes --runstatedir=/run to
856                   ./configure.
857
858           -       The cmake buildsystem now passes
859                   -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
860
861           -       dh_installman will now prefer detecting the language from
862                   the path name rather than the extension.
863
864           -       dh_auto_install will now only create the destination
865                   directory it needs.  Previously, it would create the
866                   package build directory for all packages.  This will not
867                   affect packages that only build with debhelper commands,
868                   but it may expose bugs in commands not included in
869                   debhelper.
870
871           -       The helpers dh_installdocs, dh_installexamples,
872                   dh_installinfo, and dh_installman now error out if their
873                   config has a pattern that does not match anything or
874                   reference a path that does not exist.
875
876                   Known exceptions include building with the nodoc profile,
877                   where the above tools will silently permit failed matches
878                   where the patterns are used to specify documentation.
879
880           -       The helpers dh_installdocs, dh_installexamples,
881                   dh_installinfo, and dh_installman now accept the parameter
882                   --sourcedir with same meaning as dh_install. Furthermore,
883                   they now also fall back to debian/tmp like dh_install.
884
885                   Migration note: A bug in debhelper 11 up to 11.1.5 made
886                   dh_installinfo incorrectly ignore --sourcedir.
887
888           -       The perl-makemaker and perl-build build systems no longer
889                   pass -I. to perl.  Packages that still need this behaviour
890                   can emulate it by using the PERL5LIB environment variable.
891                   E.g. by adding export PERL5LIB=. in their debian/rules file
892                   (or similar).
893
894           -       The PERL_USE_UNSAFE_INC environment variable is no longer
895                   set by dh or any of the dh_auto_* tools.  It was added as a
896                   temporary work around to avoid a lot of packages failing to
897                   build at the same time.
898
899                   Note this item will eventually become obsolete as upstream
900                   intends to drop support for the PERL_USE_UNSAFE_INC
901                   environment variable.  When perl drops support for it, then
902                   this variable will be removed retroactively from existing
903                   compat levels as well.
904
905           -       The dh_makeshlibs helper will now exit with an error if
906                   objdump returns a non-zero exit from analysing a given
907                   file.
908
909           -       The dh_installdocs and dh_installexamples tools may now
910                   install most of the documentation in a different path to
911                   comply with the recommendation from Debian policy §12.3
912                   (since version 3.9.7).
913
914                   Note that if a given source package only contains a single
915                   binary package in debian/control or none of the packages
916                   are -doc packages, then this change is not relevant for
917                   that source package and you can skip to the next change.
918
919                   By default, these tools will now attempt to determine a
920                   "main package for the documentation" (called a doc-main-
921                   package from here on) for every -doc package.  If they find
922                   such a doc-main-package, they will now install the
923                   documentation into the path /usr/share/doc/doc-main-package
924                   in the given doc package.  I.e. the path can change but the
925                   documentation is still shipped in the -doc package.
926
927                   The --doc-main-package option can be used when the auto-
928                   detection is insufficient or to reset the path to its
929                   previous value if there is a reason to diverge from Debian
930                   policy recommendation.
931
932                   Some documentation will not be affected by this change.
933                   These exceptions include the copyright file, changelog
934                   files, README.Debian, etc.  These files will still be
935                   installed in the path /usr/share/doc/package.
936
937           -       The dh_strip and dh_shlibdeps tools no longer uses filename
938                   patterns to determine which files to process.  Instead,
939                   they open the file and look for an ELF header to determine
940                   if a given file is an shared object or an ELF executable.
941
942                   This change may cause the tools to process more files than
943                   previously.
944
945       v12 Changes from v11 are:
946
947           -       The dh_makeshlibs tool now generates shlibs files with
948                   versioned dependency by default.  This means that
949                   -VUpstream-Version (a.k.a. -V) is now the default.
950
951                   If an unversioned dependency in the shlibs file is wanted,
952                   this can be obtained by passing -VNone instead.  However,
953                   please see dh_makeshlibs(1) for the caveat of unversioned
954                   dependencies.
955
956           -       The -s (--same-arch) option is removed.  Please use -a
957                   (--arch) instead.
958
959           -       Invoking dh_clean -k now causes an error instead of a
960                   deprecation warning.
961
962           -       The --no-restart-on-upgrade option in dh_installinit has
963                   been removed.  Please use the new name --no-stop-on-upgrade
964
965           -       There was a bug in the doit (and similar) functions from
966                   Debian::Debhelper::Dh_Lib that made them spawn a shell in
967                   one particular circumstance.  This bug is now removed and
968                   will cause helpers that rely on the bug to fail with a
969                   "command not found"-error.
970
971           -       The --list-missing and --fail-missing in dh_install has
972                   been removed.  Please use dh_missing and its corresponding
973                   options, which can also see the files installed by other
974                   helpers.
975
976           -       The dh_installinit helper no longer installs configuration
977                   for the upstart init system.  Instead, it will abort the
978                   build if it finds an old upstart configuration file.  The
979                   error is there to remind the package maintainer to ensure
980                   the proper removal of the conffiles shipped in previous
981                   versions of the package (if any).
982
983           -       The dh_installdeb tool will do basic validation of some
984                   dpkg-maintscript-helper(1) commands and will error out if
985                   the commands appear to be invalid.
986
987           -       The dh_missing tool will now default to --list-missing.
988
989           -       The dh_makeshlibs tool will now only pass libraries to
990                   dpkg-gensymbols(1) if the ELF binary has a SONAME
991                   (containing ".so").
992
993           -       The dh_compress tool no longer compresses examples (i.e.
994                   anything installed in </usr/share/doc/package/examples>.)
995
996           -       The standard sequence in dh now includes dh_dwz and
997                   dh_installinitramfs by default.  This makes the dwz and
998                   installinitramfs sequences obsolete and they will now fail
999                   with an error.  If you want to skip these commands, then
1000                   please insert an empty override target for them in
1001                   debian/rules (e.g. override_dh_dwz:)
1002
1003           -       The build systems meson and autoconf no longer explicitly
1004                   set the --libexecdir variable and thus relies on the build
1005                   system default - which should be /usr/libexec (per FHS 3.0,
1006                   adopted in Debian Policy 4.1.5).
1007
1008                   If a particular upstream package does not use the correct
1009                   default, the parameter can often be passed manually via
1010                   dh_auto_configure(1).  E.g.  via the following example:
1011
1012                       override_dh_auto_configure:
1013                           dh_auto_configure -- --libexecdir=/usr/libexec
1014
1015                   Note the -- before the --libexecdir parameter.
1016
1017           -       Retroactively removed in debhelper/13.5:
1018
1019                   The dh_installdeb tool would no longer installs the
1020                   maintainer provided conffiles file as it was deemed
1021                   unnecessary.  However, the remove-on-upgrade from dpkg/1.20
1022                   made the file relevant again and dh_installdeb now installs
1023                   it again in compat levels 12+.
1024
1025           -       The dh_installsystemd tool no longer relies on
1026                   dh_installinit for handling systemd services that have a
1027                   sysvinit alternative.  Both tools must now be used in such
1028                   a case to ensure the service is properly started under both
1029                   sysvinit and systemd.
1030
1031                   If you have an override for dh_installinit (e.g. to call it
1032                   with --no-start) then you will probably need one for
1033                   dh_installsystemd as well now.
1034
1035                   This change makes dh_installinit inject a misc:Pre-Depends
1036                   for init-system-helpers (>= 1.54~).  Please ensure that the
1037                   package lists ${misc:Pre-Depends} in its Pre-Depends field
1038                   before upgrading to compat 12.
1039
1040           -       The third-party dh_golang tool (from dh-golang package) now
1041                   defaults on honoring DH_GOLANG_EXCLUDES variable for source
1042                   installation in -dev packages and not only during the
1043                   building process. Please set DH_GOLANG_EXCLUDES_ALL to
1044                   false to revert to the previous behaviour. See
1045                   Debian::Debhelper::Buildsystem::golang(3pm) for details and
1046                   examples.
1047
1048           -       dh_installsystemduser is now included in the dh standard
1049                   sequence by default.
1050
1051           -       The python-distutils buildsystem is now removed.  Please
1052                   use the third-party build system pybuild instead.
1053
1054       v13 This is the recommended mode of operation.
1055
1056           Changes from v12 are:
1057
1058           -       The meson+ninja build system now uses meson test instead of
1059                   ninja test when running the test suite.  Any override of
1060                   dh_auto_test that passes extra parameters to upstream test
1061                   runner should be reviewed as meson test is not command line
1062                   compatible with ninja test.
1063
1064           -       All debhelper like tools based on the official debhelper
1065                   library (including dh and the official dh_* tools) no
1066                   longer accepts abbreviated command parameters.  At the same
1067                   time, dh now optimizes out calls to redundant dh_* helpers
1068                   even when passed long command line options.
1069
1070           -       The ELF related debhelper tools (dh_dwz, dh_strip,
1071                   dh_makeshlibs, dh_shlibdeps) are now only run for arch
1072                   dependent packages by default (i.e. they are excluded from
1073                   *-indep targets and are passed -a by default). If you need
1074                   them for *-indep targets, you can add an explicit Build-
1075                   Depends on dh-sequence-elf-tools.
1076
1077           -       The third-party gradle build system (from gradle-debian-
1078                   helper package) now runs the upstream-provided test suite
1079                   automatically.  To suppress such behavior, override
1080                   dh_auto_test.
1081
1082           -       The dh_installman tool now aborts if it sees conflicting
1083                   definitions of a manpage.  This typically happens if the
1084                   upstream build system is installing a compressed version
1085                   and the package lists an uncompressed version of the
1086                   manpage in debian/package.manpages.  Often the easiest fix
1087                   is to remove the manpage from debian/package.manpages
1088                   (assuming both versions are identical).
1089
1090           -       The dh_auto_* helpers now reset the environment variables
1091                   HOME and common XDG_* variable.  Please see description of
1092                   the environment variables in "ENVIRONMENT" for how this is
1093                   handled.
1094
1095                   This feature changed between debhelper 13 and debhelper
1096                   13.2.
1097
1098           -       The dh command will now error if an override or hook target
1099                   for an obsolete command are present in debian/rules (e.g.
1100                   override_dh_systemd_enable:).
1101
1102           -       The dh_missing command will now default to --fail-missing.
1103                   This can be reverted to a non-fatal warning by explicitly
1104                   passing --list-missing like it was in compat 12.
1105
1106                   If you do not want the warning either, please omit the call
1107                   to dh_missing.  If you use the dh command sequencer, then
1108                   you can do this by inserting an empty override target in
1109                   the debian/rules file of the relevant package.  As an
1110                   example:
1111
1112                       # Disable dh_missing
1113                       override_dh_missing:
1114
1115           -       The dh command sequencer now runs dh_installtmpfiles in the
1116                   default sequence.  The dh_installtmpfiles takes over
1117                   handling of tmpfiles.d configuration files.  Related
1118                   functionality in dh_installsystemd is now disabled.
1119
1120                   Note that dh_installtmpfiles responds to
1121                   debian/package.tmpfiles where dh_installsystemd used a name
1122                   without the trailing "s".
1123
1124           -       Many dh_* tools now support limited variable expansion via
1125                   the ${foo} syntax.  In many cases, this can be used to
1126                   reference paths that contain either spaces or
1127                   dpkg-architecture(1) values.  While this can reduce the
1128                   need for dh-exec(1) in some cases, it is not a replacement
1129                   dh-exec(1) in general.  If you need filtering, renaming,
1130                   etc., the package will still need dh-exec(1).
1131
1132                   Please see "Substitutions in debhelper config files" for
1133                   syntax and available substitution variables.  To dh_* tool
1134                   writers, substitution expansion occurs as a part of the
1135                   filearray and filedoublearray functions.
1136
1137           -       The dh command sequencer will now skip all hook and
1138                   override targets for dh_auto_test, dh_dwz and dh_strip when
1139                   DEB_BUILD_OPTIONS lists the relevant nocheck / nostrip
1140                   options.
1141
1142                   Any package relying on these targets to always be run
1143                   should instead move relevant logic out of those targets.
1144                   E.g. non-test related packaging code from
1145                   override_dh_auto_test would have to be moved to
1146                   execute_after_dh_auto_build or
1147                   execute_before_dh_auto_install.
1148
1149           -       The cmake buildsystem now passes
1150                   -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON to cmake(1) to speed
1151                   up automatic installation process. If for some reason you
1152                   need previous behavior, override the flag:
1153
1154                       dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...
1155
1156       v14 This compatibility level is still open for development; use with
1157           caution.
1158
1159           Changes from v13 are:
1160
1161           -       The cmake buildsystem now passes -DCMAKE_SKIP_RPATH=ON and
1162                   -DCMAKE_BUILD_RPATH_USE_ORIGIN=ON to cmake(1) to avoid some
1163                   reproducibility issues.
1164
1165                   This can cause issues with running binaries directly from
1166                   the build directories as they might now require a manually
1167                   set LD_LIBRARY_PATH.  If you need to override this change,
1168                   we recommend that you try to pass the
1169                   -DCMAKE_SKIP_RPATH=OFF option first to see if that fixes
1170                   the problem (leaving CMAKE_BUILD_RPATH_USE_ORIGIN at its
1171                   new default).  This should undo the need for
1172                   LD_LIBRARY_PATH and avoid the reproducibility issues on
1173                   Linux, where $ORIGIN is supported by the runtime linkers.
1174
1175           -       The tool dh_installsysusers is now included in the default
1176                   sequence.
1177
1178           -       Use of the dh_gconf command in override and hook targets
1179                   now causes an error.  The dh_gconf command has been a no-op
1180                   for years and was removed in debhelper 13.4.
1181
1182           -       The dh sequencer will warn if the single-binary addon is
1183                   implicitly activated to warn maintainers of the pending
1184                   compat 15 change in dh_auto_install.
1185
1186                   Maintainers are urged to either explicitly activate the
1187                   single-binary addon to preserve the existing behaviour
1188                   (e.g., by adding dh-sequence-single-binary to Build-
1189                   Depends), or explicitly passing --destdir to
1190                   dh_auto_install if used and then passing --without single-
1191                   binary to dh (the latter to silence the warning).
1192
1193                   The rationale for this change to avoid "surprises" when
1194                   adding a second binary package later.  Previously,
1195                   debhelper would silently change behaviour often resulting
1196                   in empty binary packages being uploaded to the archive by
1197                   mistake. With the new behaviour, the single-binary addon
1198                   will detect the mismatch and warn the maintainer of what is
1199                   about to happen.
1200
1201       v15 This compatibility level is still open for development; use with
1202           caution.
1203
1204           Changes from v14 are:
1205
1206           -       The dh_auto_install tool no longer defaults to
1207                   --destdir=debian/package for source packages only producing
1208                   a single binary.  If this behaviour is wanted, the package
1209                   should explicitly activate the single-binary dh addon
1210                   (e.g., by adding dh-sequence-single-binary to Build-
1211                   Depends) or pass --destdir to dh_auto_install.
1212
1213                   The rationale for this change to avoid "surprises" when
1214                   adding a second binary package later.  Previously,
1215                   debhelper would silently change behaviour often resulting
1216                   in empty binary packages being uploaded to the archive by
1217                   mistake. With the new behaviour, the single-binary addon
1218                   will detect the mismatch and warn the maintainer of what is
1219                   about to happen.
1220

NOTES

1222   Multiple binary package support
1223       If your source package generates more than one binary package,
1224       debhelper programs will default to acting on all binary packages when
1225       run. If your source package happens to generate one architecture
1226       dependent package, and another architecture independent package, this
1227       is not the correct behavior, because you need to generate the
1228       architecture dependent packages in the binary-arch debian/rules target,
1229       and the architecture independent packages in the binary-indep
1230       debian/rules target.
1231
1232       To facilitate this, as well as give you more control over which
1233       packages are acted on by debhelper programs, all debhelper programs
1234       accept the -a, -i, -p, and -s parameters. These parameters are
1235       cumulative.  If none are given, debhelper programs default to acting on
1236       all packages listed in the control file, with the exceptions below.
1237
1238       First, any package whose Architecture field in debian/control does not
1239       match the DEB_HOST_ARCH architecture will be excluded ("Debian Policy,
1240       section 5.6.8").
1241
1242       Also, some additional packages may be excluded based on the contents of
1243       the DEB_BUILD_PROFILES environment variable and Build-Profiles fields
1244       in binary package stanzas in debian/control, according to the draft
1245       policy at <https://wiki.debian.org/BuildProfileSpec>.
1246
1247       Interaction between package selections and Build-Profiles
1248
1249       Build-Profiles affect which packages are included in the package
1250       selections mechanisms in debhelper.  Generally, the package selections
1251       are described from the assumption that all packages are enabled.  This
1252       section describes how the selections react when a package is disabled
1253       due to the active Build-Profiles (or lack of active Build-Profiles).
1254
1255       -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)
1256           The package disabled by Build-Profiles is silently excluded from
1257           the selection.
1258
1259           Note you will receive a warning if all packages related to these
1260           selections are disabled.  In that case, it generally does not make
1261           sense to do the build in the first place.
1262
1263       -N package / --no-package package
1264           The option is accepted and effectively does nothing.
1265
1266       -p package / --package package
1267           The option is accepted, but debhelper will not act on the package.
1268
1269       Note that it does not matter whether a package is enabled or disabled
1270       by default.
1271
1272   Automatic generation of Debian install scripts
1273       Some debhelper commands will automatically generate parts of Debian
1274       maintainer scripts. If you want these automatically generated things
1275       included in your existing Debian maintainer scripts, then you need to
1276       add #DEBHELPER# to your scripts, in the place the code should be added.
1277       #DEBHELPER# will be replaced by any auto-generated code when you run
1278       dh_installdeb.
1279
1280       If a script does not exist at all and debhelper needs to add something
1281       to it, then debhelper will create the complete script.
1282
1283       All debhelper commands that automatically generate code in this way let
1284       it be disabled by the -n parameter (see above).
1285
1286       Note that the inserted code will be shell code, so you cannot directly
1287       use it in a Perl script. If you would like to embed it into a Perl
1288       script, here is one way to do that (note that I made sure that $1, $2,
1289       etc are set with the set command):
1290
1291         my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
1292         #DEBHELPER#
1293         EOF
1294         if (system($temp)) {
1295            my $exit_code = ($? >> 8) & 0xff;
1296            my $signal = $? & 0x7f;
1297            if ($exit_code) {
1298                die("The debhelper script failed with error code: ${exit_code}");
1299            } else {
1300                die("The debhelper script was killed by signal: ${signal}");
1301            }
1302         }
1303
1304   Automatic generation of miscellaneous dependencies.
1305       Some debhelper commands may make the generated package need to depend
1306       on some other packages. For example, if you use dh_installdebconf(1),
1307       your package will generally need to depend on debconf. Or if you use
1308       dh_installxfonts(1), your package will generally need to depend on a
1309       particular version of xutils. Keeping track of these miscellaneous
1310       dependencies can be annoying since they are dependent on how debhelper
1311       does things, so debhelper offers a way to automate it.
1312
1313       All commands of this type, besides documenting what dependencies may be
1314       needed on their man pages, will automatically generate a substvar
1315       called ${misc:Depends}. If you put that token into your debian/control
1316       file, it will be expanded to the dependencies debhelper figures you
1317       need.
1318
1319       This is entirely independent of the standard ${shlibs:Depends}
1320       generated by dh_makeshlibs(1), and the ${perl:Depends} generated by
1321       dh_perl(1).  You can choose not to use any of these, if debhelper's
1322       guesses don't match reality.
1323
1324   Package build directories
1325       By default, all debhelper programs assume that the temporary directory
1326       used for assembling the tree of files in a package is debian/package.
1327
1328       Sometimes, you might want to use some other temporary directory. This
1329       is supported by the -P flag. For example, "dh_installdocs
1330       -Pdebian/tmp", will use debian/tmp as the temporary directory. Note
1331       that if you use -P, the debhelper programs can only be acting on a
1332       single package at a time. So if you have a package that builds many
1333       binary packages, you will need to also use the -p flag to specify which
1334       binary package the debhelper program will act on.
1335
1336   udebs
1337       Debhelper includes support for udebs. To create a udeb with debhelper,
1338       add "Package-Type: udeb" to the package's stanza in debian/control.
1339       Debhelper will try to create udebs that comply with debian-installer
1340       policy, by making the generated package files end in .udeb, not
1341       installing any documentation into a udeb, skipping over preinst,
1342       postrm, prerm, and config scripts, etc.
1343

ENVIRONMENT

1345       This section describes some of the environment variables that
1346       influences the behaviour of debhelper or which debhelper interacts
1347       with.
1348
1349       It is important to note that these must be actual environment variables
1350       in order to affect the behaviour of debhelper (not simply Makefile
1351       variables).  To specify them properly in debian/rules, be sure to
1352       "export" them. For example, "export DH_VERBOSE".
1353
1354       DH_VERBOSE
1355           Set to 1 to enable verbose mode. Debhelper will output every
1356           command it runs. Also enables verbose build logs for some build
1357           systems like autoconf.
1358
1359       DH_QUIET
1360           Set to 1 to enable quiet mode. Debhelper will not output commands
1361           calling the upstream build system nor will dh print which
1362           subcommands are called and depending on the upstream build system
1363           might make that more quiet, too.  This makes it easier to spot
1364           important messages but makes the output quite useless as buildd
1365           log.  Ignored if DH_VERBOSE is also set.
1366
1367       DH_COMPAT
1368           Temporarily specifies what compatibility level debhelper should run
1369           at, overriding any value specified via Build-Depends on debhelper-
1370           compat or via the debian/compat file.
1371
1372       DH_NO_ACT
1373           Set to 1 to enable no-act mode.
1374
1375       DH_OPTIONS
1376           All debhelper tools will parse command line arguments listed in
1377           this variable before any command option (as if they had been
1378           prepended to the command line arguments).  Unfortunately, some
1379           third-party provided tools may not support this variable and will
1380           ignore these command line arguments.
1381
1382           When using dh(1), it can be passed options that will be passed on
1383           to each debhelper command, which is generally better than using
1384           DH_OPTIONS.
1385
1386       DH_ALWAYS_EXCLUDE
1387           If set, this adds the value the variable is set to to the -X
1388           options of all commands that support the -X option. Moreover,
1389           dh_builddeb will rm -rf anything that matches the value in your
1390           package build tree.
1391
1392           This can be useful if you are doing a build from a CVS source tree,
1393           in which case setting DH_ALWAYS_EXCLUDE=CVS will prevent any CVS
1394           directories from sneaking into the package you build. Or, if a
1395           package has a source tarball that (unwisely) includes CVS
1396           directories, you might want to export DH_ALWAYS_EXCLUDE=CVS in
1397           debian/rules, to make it take effect wherever your package is
1398           built.
1399
1400           Multiple things to exclude can be separated with colons, as in
1401           DH_ALWAYS_EXCLUDE=CVS:.svn
1402
1403       DH_EXTRA_ADDONS
1404           If set, this adds the specified dh addons to be run in the
1405           appropriate places in the sequence of commands. This is equivalent
1406           to specifying the addon to run with the --with flag in the
1407           debian/rules file. Any --without calls specifying an addon in this
1408           environment variable will not be run.
1409
1410           This is intended to be used by downstreams or specific local
1411           configurations that require a debhelper addon to be run during
1412           multiple builds without having to patch a large number of rules
1413           file. If at all possible, this should be avoided in favor of a
1414           --with flag in the rules file.
1415
1416       DH_COLORS, DPKG_COLORS
1417           These variables can be used to control whether debhelper commands
1418           should use colors in their textual output.  Can be set to "always",
1419           "auto" (the default), or "never".
1420
1421           Note that DPKG_COLOR also affects a number of dpkg related tools
1422           and debhelper uses it on the assumption that you want the same
1423           color setting for dpkg and debhelper.  In the off-hand chance you
1424           want different color setting for debhelper, you can use DH_COLORS
1425           instead or in addition to DPKG_COLORS.
1426
1427       NO_COLOR
1428           If no explicit request for color has been given (e.g. DH_COLORS and
1429           DPKG_COLORS are both unset), the presence of this environment
1430           variable cause the default color setting to be "never".
1431
1432           The variable is defined according to <https://no-color.org/>.  In
1433           this project, the environment variables (such as DH_COLORS) are
1434           considered an explicit request for color.
1435
1436       CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS,
1437       FCFLAGS, LDFLAGS
1438           By default (in any non-deprecated compat level), debhelper will
1439           automatically set these flags by using dpkg-buildflags(1), when
1440           they are unset.  If you need to change the default flags, please
1441           use the features from dpkg-buildflags(1) to do this (e.g.
1442           DEB_BUILD_MAINT_OPTIONS=hardening=all or
1443           DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true) rather than setting
1444           the concrete variable directly.
1445
1446       HOME, XDG_*
1447           In compat 13 and later, these environment variables are reset
1448           before invoking the upstream build system via the dh_auto_*
1449           helpers.  The variables HOME (all dh_auto_* helpers) and
1450           XDG_RUNTIME_DIR (dh_auto_test only) will be set to a writable
1451           directory. All remaining variables and XDG_RUNTIME_DIR (except for
1452           during dh_auto_test) will be cleared.
1453
1454           The HOME directory will be created as an empty directory but it
1455           will be reused between calls to dh_auto_*.  Any content will
1456           persist until explicitly deleted or dh_clean.
1457
1458       DEB_BUILD_OPTIONS
1459           Please see "Supported flags in DEB_BUILD_OPTIONS" for this
1460           environment variable.
1461
1462           Please note that this variable should not be altered by package
1463           maintainers inside debian/rules to change the behaviour of
1464           debhelper.  Instead, where the package maintainer need these
1465           features, they should look disabling the relevant feature directly
1466           (e.g. by overriding the concrete tools).
1467
1468       DEB_MAINT_BUILD_OPTIONS
1469           This is a dpkg specific environment variable (see e.g.
1470           dpkg-buildflags(1)).  The debhelper tool suite silently ignores it.
1471
1472           It is documented here because it has a similar name to
1473           DEB_BUILD_OPTIONS, which make some people mistakenly assume that
1474           debhelper will also react to this variable.
1475
1476   Supported flags in DEB_BUILD_OPTIONS
1477       The debhelper tool suite reacts to the following flags in
1478       DEB_BUILD_OPTIONS.
1479
1480       dherroron=obsolete-compat-levels
1481           This is a debhelper specific value.
1482
1483           When dherroron is present and set to obsolete-compat-levels, then
1484           debhelper tools will promote deprecation warnings for usage of old
1485           soon to be removed compat levels into errors.
1486
1487           This is useful for automated checking for code relying on
1488           deprecated compat levels that is scheduled for removal.
1489
1490           This option is intended for testing purposes; not production
1491           builds.
1492
1493       nostrip
1494           This value will change the content of the debs being built.  The
1495           .deb packages built when this is set is therefore not bit-for-bit
1496           reproducible with a regular build in the general case.
1497
1498           This value will cause the official debhelper tools will skip
1499           actions and helpers that either remove, detach or deduplicate
1500           debugging symbols in ELF binaries.
1501
1502           This value affects dh_dwz(1) and dh_strip(1).
1503
1504       nocheck
1505           This value will cause the official debhelper build systems to skip
1506           runs of upstream test suites.
1507
1508           Package maintainers looking to avoid running the upstream tests
1509           should not rely on this.  Instead, they can add an empty override
1510           target to skip dh_auto_test.
1511
1512           This value affects dh_auto_test(1).
1513
1514       nodoc
1515           This value will change the content of the debs being built.  The
1516           .deb packages built when this is set is therefore not bit-for-bit
1517           reproducible with a regular build in the general case.
1518
1519           This value will cause several debhelper tools to skip installation
1520           of documentation such as manpages or upstream provided
1521           documentation.  Additionally, the tools will also ignore if
1522           declared documentation is "missing" on the assumption that the
1523           documentation has not been built.
1524
1525           This value effects tools like dh_installdocs(1), which knows it is
1526           working with documentation.
1527
1528       noautodbgsym, noddebs
1529           The official name is autodbgsym.  The noddebs variant is accepted
1530           for historical reasons.
1531
1532           This value causes debhelper to skip the generation of automatically
1533           generated debug symbol packages.
1534
1535           This value affects dh_strip(1).
1536
1537       parallel=N
1538           This value enables debhelper to use up to N threads or processes
1539           (subject to parameters like --no-parallel and --max-parallel=M).
1540           Not all debhelper tools work with parallel tasks and may silently
1541           ignore the request.
1542
1543           This value affects many debhelper tools.  Most notably dh_auto_*,
1544           which will attempt to run the underlying upstream build system with
1545           that number of threads.
1546
1547       terse
1548           This value will cause the official debhelper build systems to
1549           configure upstream builds to be terse (i.e. reduce verbosity in
1550           their output).  This is subject to the upstream and the debhelper
1551           build system supporting such features.
1552
1553           This value affects most dh_auto_* tools.
1554
1555       Unknown flags are silently ignored.
1556
1557       Note third-party debhelper-like tools or third-party provided build
1558       systems may or may not react to the above flags.  This tends to depend
1559       on implementation details of the tool.
1560

SEE ALSO

1562       /usr/share/doc/debhelper/examples/
1563           A set of example debian/rules files that use debhelper.
1564
1565       <http://joeyh.name/code/debhelper/>
1566           Debhelper web site.
1567

AUTHOR

1569       Joey Hess <joeyh@debian.org>
1570
1571
1572
157313.5.2                            2021-11-02                      debhelper(7)
Impressum