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

COMMON DEBHELPER OPTIONS

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

BUILD SYSTEM OPTIONS

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

COMPATIBILITY LEVELS

580       From time to time, major non-backwards-compatible changes need to be
581       made to debhelper, to keep it clean and well-designed as needs change
582       and its author gains more experience. To prevent such major changes
583       from breaking existing packages, the concept of debhelper compatibility
584       levels was introduced. You must tell debhelper which compatibility
585       level it should use, and it modifies its behavior in various ways.
586
587       In current debhelper, you can specify the compatibility level in
588       debian/control by adding a Build-Depends on the debhelper-compat
589       package.  For example, to use v13 mode, ensure debian/control has:
590
591         Build-Depends: debhelper-compat (= 13)
592
593       This also serves as an appropriate versioned build dependency on a
594       sufficient version of the debhelper package, so you do not need to
595       specify a separate versioned build dependency on the debhelper package
596       unless you need a specific point release of debhelper (such as for the
597       introduction of a new feature or bugfix within a compatibility level).
598
599       Note that debhelper does not provide debhelper-compat for experimental
600       or beta compatibility levels; packages experimenting with those
601       compatibility levels should use debian/compat (or, if only for selected
602       commands, DH_COMPAT).
603
604       Prior versions of debhelper required specifying the compatibility level
605       in the file debian/compat, and current debhelper still supports this
606       for backward compatibility. To use this method, the debian/compat file
607       should contain the compatibility level as a single number, and no other
608       content. If you specify the compatibility level by this method, your
609       package will also need a versioned build dependency on a version of the
610       debhelper package equal to (or greater than) the compatibility level
611       your package uses. So, if you specify compatibility level 13 in
612       debian/compat, ensure debian/control has:
613
614         Build-Depends: debhelper (>= 13~)
615
616       Note that you must use either the build-dependency on debhelper-compat
617       or the debian/compat file. Whenever possible, the debhelper-compat
618       build-dependency is recommended.
619
620       If needed be, the DH_COMPAT environment variable can be used to
621       override the compat level for a given command.  The feature is mostly
622       useful for either temporarily upgrading a few commands to a new compat
623       level or keeping a few commands on a lower compat level.  The feature
624       is best used sparingly as it effectively introduces special-cases into
625       the debian/rules file that may be surprising to maintainers or
626       reviewers (or, in the long term, to yourself).
627
628       Unless otherwise indicated, all debhelper documentation assumes that
629       you are using the most recent compatibility level, and in most cases
630       does not indicate if the behavior is different in an earlier
631       compatibility level, so if you are not using the most recent
632       compatibility level, you're advised to read below for notes about what
633       is different in earlier compatibility levels.
634
635   Supported compatibility levels
636       The list of supported compatibility levels and the related upgrade
637       check list has moved to debhelper-compat-upgrade-checklist(7).
638

NOTES

640   Multiple binary package support
641       If your source package generates more than one binary package,
642       debhelper programs will default to acting on all binary packages when
643       run. If your source package happens to generate one architecture
644       dependent package, and another architecture independent package, this
645       is not the correct behavior, because you need to generate the
646       architecture dependent packages in the binary-arch debian/rules target,
647       and the architecture independent packages in the binary-indep
648       debian/rules target.
649
650       To facilitate this, as well as give you more control over which
651       packages are acted on by debhelper programs, all debhelper programs
652       accept the -a, -i, -p, and -s parameters. These parameters are
653       cumulative.  If none are given, debhelper programs default to acting on
654       all packages listed in the control file, with the exceptions below.
655
656       First, any package whose Architecture field in debian/control does not
657       match the DEB_HOST_ARCH architecture will be excluded ("Debian Policy,
658       section 5.6.8").
659
660       Also, some additional packages may be excluded based on the contents of
661       the DEB_BUILD_PROFILES environment variable and Build-Profiles fields
662       in binary package stanzas in debian/control, according to the draft
663       policy at <https://wiki.debian.org/BuildProfileSpec>.
664
665       Interaction between package selections and Build-Profiles
666
667       Build-Profiles affect which packages are included in the package
668       selections mechanisms in debhelper.  Generally, the package selections
669       are described from the assumption that all packages are enabled.  This
670       section describes how the selections react when a package is disabled
671       due to the active Build-Profiles (or lack of active Build-Profiles).
672
673       -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)
674           The package disabled by Build-Profiles is silently excluded from
675           the selection.
676
677           Note you will receive a warning if all packages related to these
678           selections are disabled.  In that case, it generally does not make
679           sense to do the build in the first place.
680
681       -N package / --no-package package
682           The option is accepted and effectively does nothing.
683
684       -p package / --package package
685           The option is accepted, but debhelper will not act on the package.
686
687       Note that it does not matter whether a package is enabled or disabled
688       by default.
689
690   Automatic generation of Debian install scripts
691       Some debhelper commands will automatically generate parts of Debian
692       maintainer scripts. If you want these automatically generated things
693       included in your existing Debian maintainer scripts, then you need to
694       add #DEBHELPER# to your scripts, in the place the code should be added.
695       #DEBHELPER# will be replaced by any auto-generated code when you run
696       dh_installdeb.
697
698       If a script does not exist at all and debhelper needs to add something
699       to it, then debhelper will create the complete script.
700
701       All debhelper commands that automatically generate code in this way let
702       it be disabled by the -n parameter (see above).
703
704       Note that the inserted code will be shell code, so you cannot directly
705       use it in a Perl script. If you would like to embed it into a Perl
706       script, here is one way to do that (note that I made sure that $1, $2,
707       etc are set with the set command):
708
709         my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
710         #DEBHELPER#
711         EOF
712         if (system($temp)) {
713            my $exit_code = ($? >> 8) & 0xff;
714            my $signal = $? & 0x7f;
715            if ($exit_code) {
716                die("The debhelper script failed with error code: ${exit_code}");
717            } else {
718                die("The debhelper script was killed by signal: ${signal}");
719            }
720         }
721
722   Automatic generation of miscellaneous dependencies.
723       Some debhelper commands may make the generated package need to depend
724       on some other packages. For example, if you use dh_installdebconf(1),
725       your package will generally need to depend on debconf. Or if you use
726       dh_installxfonts(1), your package will generally need to depend on a
727       particular version of xutils. Keeping track of these miscellaneous
728       dependencies can be annoying since they are dependent on how debhelper
729       does things, so debhelper offers a way to automate it.
730
731       All commands of this type, besides documenting what dependencies may be
732       needed on their man pages, will automatically generate a substvar
733       called ${misc:Depends}. If you put that token into your debian/control
734       file, it will be expanded to the dependencies debhelper figures you
735       need.
736
737       This is entirely independent of the standard ${shlibs:Depends}
738       generated by dh_makeshlibs(1), and the ${perl:Depends} generated by
739       dh_perl(1).  You can choose not to use any of these, if debhelper's
740       guesses don't match reality.
741
742   Package build directories
743       By default, all debhelper programs assume that the temporary directory
744       used for assembling the tree of files in a package is debian/package.
745
746       Sometimes, you might want to use some other temporary directory. This
747       is supported by the -P flag. For example, "dh_installdocs
748       -Pdebian/tmp", will use debian/tmp as the temporary directory. Note
749       that if you use -P, the debhelper programs can only be acting on a
750       single package at a time. So if you have a package that builds many
751       binary packages, you will need to also use the -p flag to specify which
752       binary package the debhelper program will act on.
753
754   udebs
755       Debhelper includes support for udebs. To create a udeb with debhelper,
756       add "Package-Type: udeb" to the package's stanza in debian/control.
757       Debhelper will try to create udebs that comply with debian-installer
758       policy, by making the generated package files end in .udeb, not
759       installing any documentation into a udeb, skipping over preinst,
760       postrm, prerm, and config scripts, etc.
761

ENVIRONMENT

763       This section describes some of the environment variables that
764       influences the behaviour of debhelper or which debhelper interacts
765       with.
766
767       It is important to note that these must be actual environment variables
768       in order to affect the behaviour of debhelper (not simply Makefile
769       variables).  To specify them properly in debian/rules, be sure to
770       "export" them. For example, "export DH_VERBOSE".
771
772       DH_VERBOSE
773           Set to a non-empty value to enable verbose mode.  Please see the -v
774           / --verbose option for details.
775
776       DH_QUIET
777           Set to a non-empty value to enable quiet mode. Debhelper will not
778           output commands calling the upstream build system nor will dh print
779           which subcommands are called and depending on the upstream build
780           system might make that more quiet, too.  This makes it easier to
781           spot important messages but makes the output quite useless as
782           buildd log.
783
784           Ignored if DH_VERBOSE is also set or -v / --verbose is passed.
785
786       DH_COMPAT
787           Temporarily specifies what compatibility level debhelper should run
788           at, overriding any value specified via Build-Depends on debhelper-
789           compat or via the debian/compat file.
790
791       DH_NO_ACT
792           Set to 1 to enable no-act mode.
793
794       DH_OPTIONS
795           All debhelper tools will parse command line arguments listed in
796           this variable before any command option (as if they had been
797           prepended to the command line arguments).  Unfortunately, some
798           third-party provided tools may not support this variable and will
799           ignore these command line arguments.
800
801           When using dh(1), it can be passed options that will be passed on
802           to each debhelper command, which is generally better than using
803           DH_OPTIONS.
804
805       DH_ALWAYS_EXCLUDE
806           If set, this adds the value the variable is set to to the -X
807           options of all commands that support the -X option. Moreover,
808           dh_builddeb will rm -rf anything that matches the value in your
809           package build tree.
810
811           This can be useful if you are doing a build from a CVS source tree,
812           in which case setting DH_ALWAYS_EXCLUDE=CVS will prevent any CVS
813           directories from sneaking into the package you build. Or, if a
814           package has a source tarball that (unwisely) includes CVS
815           directories, you might want to export DH_ALWAYS_EXCLUDE=CVS in
816           debian/rules, to make it take effect wherever your package is
817           built.
818
819           Multiple things to exclude can be separated with colons, as in
820           DH_ALWAYS_EXCLUDE=CVS:.svn
821
822       DH_EXTRA_ADDONS
823           If set, this adds the specified dh addons to be run in the
824           appropriate places in the sequence of commands. This is equivalent
825           to specifying the addon to run with the --with flag in the
826           debian/rules file. Any --without calls specifying an addon in this
827           environment variable will not be run.
828
829           This is intended to be used by downstreams or specific local
830           configurations that require a debhelper addon to be run during
831           multiple builds without having to patch a large number of rules
832           file. If at all possible, this should be avoided in favor of a
833           --with flag in the rules file.
834
835       DH_COLORS, DPKG_COLORS
836           These variables can be used to control whether debhelper commands
837           should use colors in their textual output.  Can be set to "always",
838           "auto" (the default), or "never".
839
840           Note that DPKG_COLOR also affects a number of dpkg related tools
841           and debhelper uses it on the assumption that you want the same
842           color setting for dpkg and debhelper.  In the off-hand chance you
843           want different color setting for debhelper, you can use DH_COLORS
844           instead or in addition to DPKG_COLORS.
845
846       NO_COLOR
847           If no explicit request for color has been given (e.g. DH_COLORS and
848           DPKG_COLORS are both unset), the presence of this environment
849           variable cause the default color setting to be "never".
850
851           The variable is defined according to <https://no-color.org/>.  In
852           this project, the environment variables (such as DH_COLORS) are
853           considered an explicit request for color.
854
855       CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS,
856       FCFLAGS, LDFLAGS
857           By default (in any non-deprecated compat level), debhelper will
858           automatically set these flags by using dpkg-buildflags(1), when
859           they are unset.  If you need to change the default flags, please
860           use the features from dpkg-buildflags(1) to do this (e.g.
861           DEB_BUILD_MAINT_OPTIONS=hardening=all or
862           DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true) rather than setting
863           the concrete variable directly.
864
865       HOME, XDG_*
866           In compat 13 and later, these environment variables are reset
867           before invoking the upstream build system via the dh_auto_*
868           helpers.  The variables HOME (all dh_auto_* helpers) and
869           XDG_RUNTIME_DIR (dh_auto_test only) will be set to a writable
870           directory. All remaining variables and XDG_RUNTIME_DIR (except for
871           during dh_auto_test) will be cleared.
872
873           The HOME directory will be created as an empty directory but it
874           will be reused between calls to dh_auto_*.  Any content will
875           persist until explicitly deleted or dh_clean.
876
877       DEB_BUILD_OPTIONS
878           Please see "Supported flags in DEB_BUILD_OPTIONS" for this
879           environment variable.
880
881           Please note that this variable should not be altered by package
882           maintainers inside debian/rules to change the behaviour of
883           debhelper.  Instead, where the package maintainer need these
884           features, they should look disabling the relevant feature directly
885           (e.g. by overriding the concrete tools).
886
887       DEB_BUILD_MAINT_OPTIONS
888           This is a dpkg specific environment variable (see e.g.
889           dpkg-buildflags(1)).  The debhelper tool suite silently ignores it.
890
891           It is documented here because it has a similar name to
892           DEB_BUILD_OPTIONS, which make some people mistakenly assume that
893           debhelper will also react to this variable.
894
895   Supported flags in DEB_BUILD_OPTIONS
896       The debhelper tool suite reacts to the following flags in
897       DEB_BUILD_OPTIONS.
898
899       dherroron=obsolete-compat-levels
900           This is a debhelper specific value.
901
902           When dherroron is present and set to obsolete-compat-levels, then
903           debhelper tools will promote deprecation warnings for usage of old
904           soon to be removed compat levels into errors.
905
906           This is useful for automated checking for code relying on
907           deprecated compat levels that is scheduled for removal.
908
909           This option is intended for testing purposes; not production
910           builds.
911
912       nostrip
913           This value will change the content of the debs being built.  The
914           .deb packages built when this is set is therefore not bit-for-bit
915           reproducible with a regular build in the general case.
916
917           This value will cause the official debhelper tools will skip
918           actions and helpers that either remove, detach or deduplicate
919           debugging symbols in ELF binaries.
920
921           This value affects dh_dwz(1) and dh_strip(1).
922
923       nocheck
924           This value will cause the official debhelper build systems to skip
925           runs of upstream test suites.
926
927           Package maintainers looking to avoid running the upstream tests
928           should not rely on this.  Instead, they can add an empty override
929           target to skip dh_auto_test.
930
931           This value affects dh_auto_test(1).
932
933       nodoc
934           This value will change the content of the debs being built.  The
935           .deb packages built when this is set is therefore not bit-for-bit
936           reproducible with a regular build in the general case.
937
938           This value will cause several debhelper tools to skip installation
939           of documentation such as manpages or upstream provided
940           documentation.  Additionally, the tools will also ignore if
941           declared documentation is "missing" on the assumption that the
942           documentation has not been built.
943
944           This value effects tools like dh_installdocs(1), which knows it is
945           working with documentation.
946
947       notrimdch
948           This value will change the content of the debs being built.  The
949           .deb packages built when this is set is therefore not bit-for-bit
950           reproducible with a regular build in the general case.
951
952           This value will cause dh_installchangelogs(1) to act as if it had
953           been passed the --no-trim option, forcing it to forgo removing
954           older entries from changelogs.
955
956       noautodbgsym, noddebs
957           The official name is noautodbgsym.  The noddebs variant is accepted
958           for historical reasons.
959
960           This value causes debhelper to skip the generation of automatically
961           generated debug symbol packages.
962
963           This value affects dh_strip(1).
964
965       parallel=N
966           This value enables debhelper to use up to N threads or processes
967           (subject to parameters like --no-parallel and --max-parallel=M).
968           Not all debhelper tools work with parallel tasks and may silently
969           ignore the request.
970
971           This value affects many debhelper tools.  Most notably dh_auto_*,
972           which will attempt to run the underlying upstream build system with
973           that number of threads.
974
975       terse
976           This value will cause the official debhelper build systems to
977           configure upstream builds to be terse (i.e. reduce verbosity in
978           their output).  This is subject to the upstream and the debhelper
979           build system supporting such features.
980
981           This value affects most dh_auto_* tools directly. For commands
982           provided by the debhelper package, it also causes the tools to act
983           like the DH_QUIET environment variable was non-empty.
984
985       Unknown flags are silently ignored.
986
987       Note third-party debhelper-like tools or third-party provided build
988       systems may or may not react to the above flags.  This tends to depend
989       on implementation details of the tool.
990

SEE ALSO

992       debhelper-compat-upgrade-checklist(7)
993           List of supported compat levels and an upgrade checklist for each
994           of them.
995
996       /usr/share/doc/debhelper/examples/
997           A set of example debian/rules files that use debhelper.
998
999       <http://joeyh.name/code/debhelper/>
1000           Debhelper web site.
1001

AUTHOR

1003       Joey Hess <joeyh@debian.org>
1004
1005
1006
100713.11.6                           2023-09-02                      debhelper(7)
Impressum