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

DEBHELPER CONFIG FILES

235       Many debhelper commands make use of files in debian/ to control what
236       they do. Besides the common debian/changelog and debian/control, which
237       are in all packages, not just those using debhelper, some additional
238       files can be used to configure the behavior of specific debhelper
239       commands. These files are typically named debian/package.foo (where
240       package of course, is replaced with the package that is being acted
241       on).
242
243       For example, dh_installdocs uses files named debian/package.docs to
244       list the documentation files it will install. See the man pages of
245       individual commands for details about the names and formats of the
246       files they use.  Generally, these files will list files to act on, one
247       file per line. Some programs in debhelper use pairs of files and
248       destinations or slightly more complicated formats.
249
250       Note for the first (or only) binary package listed in debian/control,
251       debhelper will use debian/foo when there's no debian/package.foo file.
252       However, it is often a good idea to keep the package. prefix as it is
253       more explicit.  The primary exception to this are files that debhelper
254       by default installs in every binary package when it does not have a
255       package prefix (such as debian/copyright or debian/changelog).
256
257       In some rare cases, you may want to have different versions of these
258       files for different architectures or OSes. If files named
259       debian/package.foo.ARCH or debian/package.foo.OS exist, where ARCH and
260       OS are the same as the output of "dpkg-architecture -qDEB_HOST_ARCH" /
261       "dpkg-architecture -qDEB_HOST_ARCH_OS", then they will be used in
262       preference to other, more general files.
263
264       Mostly, these config files are used to specify lists of various types
265       of files. Documentation or example files to install, files to move, and
266       so on.  When appropriate, in cases like these, you can use standard
267       shell wildcard characters (? and * and [..] character classes) in the
268       files.  You can also put comments in these files; lines beginning with
269       # are ignored.
270
271       The syntax of these files is intentionally kept very simple to make
272       them easy to read, understand, and modify.
273
274   Executable debhelper config files
275       If you need additional flexibility, many of the debhelper tools (e.g.
276       dh_install(1)) support executing a config file as a script.
277
278       To use this feature, simply mark the config file as executable (e.g.
279       chmod +x debian/package.install) and the tool will attempt to execute
280       it and use the output of the script.  In many cases, you can use
281       dh-exec(1) as interpreter of the config file to retain most of the
282       original syntax while getting the additional flexibility you need.
283
284       When using executable debhelper config files, please be aware of the
285       following:
286
287       ·   The executable config file must exit with success (i.e. its return
288           code should indicate success).
289
290       ·   The output will be used exactly as it is.  Notably, debhelper will
291           not expand wildcards or strip comments in the output.
292
293       If you need the package to build on a file system where you cannot
294       disable the executable bit, then you can use dh-exec(1) and its strip-
295       output script.
296

SHARED DEBHELPER OPTIONS

298       The following command line options are supported by all debhelper
299       programs.
300
301       -v, --verbose
302           Verbose mode: show all commands that modify the package build
303           directory.
304
305       --no-act
306           Do not really do anything. If used with -v, the result is that the
307           command will output what it would have done.
308
309       -a, --arch
310           Act on architecture dependent packages that should be built for the
311           DEB_HOST_ARCH architecture.
312
313       -i, --indep
314           Act on all architecture independent packages.
315
316       -ppackage, --package=package
317           Act on the package named package. This option may be specified
318           multiple times to make debhelper operate on a given set of
319           packages.
320
321       -s, --same-arch
322           Deprecated alias of -a.
323
324           This option is removed in compat 12.
325
326       -Npackage, --no-package=package
327           Do not act on the specified package even if an -a, -i, or -p option
328           lists the package as one that should be acted on.
329
330       --remaining-packages
331           Do not act on the packages which have already been acted on by this
332           debhelper command earlier (i.e. if the command is present in the
333           package debhelper log).  For example, if you need to call the
334           command with special options only for a couple of binary packages,
335           pass this option to the last call of the command to process the
336           rest of packages with default settings.
337
338       --ignore=file
339           Ignore the specified file. This can be used if debian/ contains a
340           debhelper config file that a debhelper command should not act on.
341           Note that debian/compat, debian/control, and debian/changelog can't
342           be ignored, but then, there should never be a reason to ignore
343           those files.
344
345           For example, if upstream ships a debian/init that you don't want
346           dh_installinit to install, use --ignore=debian/init
347
348       -Ptmpdir, --tmpdir=tmpdir
349           Use tmpdir for package build directory. The default is
350           debian/package
351
352       --mainpackage=package
353           This little-used option changes the package which debhelper
354           considers the "main package", that is, the first one listed in
355           debian/control, and the one for which debian/foo files can be used
356           instead of the usual debian/package.foo files.
357
358       -O=option|bundle
359           This is used by dh(1) when passing user-specified options to all
360           the commands it runs. If the command supports the specified option
361           or option bundle, it will take effect. If the command does not
362           support the option (or any part of an option bundle), it will be
363           ignored.
364

COMMON DEBHELPER OPTIONS

366       The following command line options are supported by some debhelper
367       programs.  See the man page of each program for a complete explanation
368       of what each option does.
369
370       -n  Do not modify postinst, postrm, etc. scripts.
371
372       -Xitem, --exclude=item
373           Exclude an item from processing. This option may be used multiple
374           times, to exclude more than one thing. The item is typically part
375           of a filename, and any file containing the specified text will be
376           excluded.
377
378       -A, --all
379           Makes files or other items that are specified on the command line
380           take effect in ALL packages acted on, not just the first.
381

BUILD SYSTEM OPTIONS

383       The following command line options are supported by all of the
384       dh_auto_* debhelper programs. These programs support a variety of build
385       systems, and normally heuristically determine which to use, and how to
386       use them.  You can use these command line options to override the
387       default behavior.  Typically these are passed to dh(1), which then
388       passes them to all the dh_auto_* programs.
389
390       -Sbuildsystem, --buildsystem=buildsystem
391           Force use of the specified buildsystem, instead of trying to auto-
392           select one which might be applicable for the package.
393
394       -Ddirectory, --sourcedir=directory, --sourcedirectory=directory
395           Assume that the original package source tree is at the specified
396           directory rather than the top level directory of the Debian source
397           package tree.
398
399       -B[directory], --builddir[=directory], --builddirectory[=directory]
400           Enable out of source building and use the specified directory as
401           the build directory. If directory parameter is omitted, a default
402           build directory will be chosen.
403
404           If this option is not specified, building will be done in source by
405           default unless the build system requires or prefers out of source
406           tree building.  In such a case, the default build directory will be
407           used even if --builddirectory is not specified.
408
409           If the build system prefers out of source tree building but still
410           allows in source building, the latter can be re-enabled by passing
411           a build directory path that is the same as the source directory
412           path.
413
414       --parallel, --no-parallel
415           Control whether parallel builds should be used if underlying build
416           system supports them.  The number of parallel jobs is controlled by
417           the DEB_BUILD_OPTIONS environment variable ("Debian Policy, section
418           4.9.1") at build time. It might also be subject to a build system
419           specific limit.
420
421           If neither option is specified, debhelper currently defaults to
422           --parallel in compat 10 (or later) and --no-parallel otherwise.
423
424           As an optimization, dh will try to avoid passing these options to
425           subprocesses, if they are unnecessary and the only options passed.
426           Notably this happens when DEB_BUILD_OPTIONS does not have a
427           parallel parameter (or its value is 1).
428
429       --max-parallel=maximum
430           This option implies --parallel and allows further limiting the
431           number of jobs that can be used in a parallel build. If the package
432           build is known to only work with certain levels of concurrency, you
433           can set this to the maximum level that is known to work, or that
434           you wish to support.
435
436           Notably, setting the maximum to 1 is effectively the same as using
437           --no-parallel.
438
439       --reload-all-buildenv-variables
440           By default, dh(1) will compute several environment (e.g. by using
441           dpkg-buildflags(1)) and cache them to avoid having all dh_auto_*
442           tool recompute them.
443
444           When passing this option, the concrete dh_auto_* tool will ignore
445           the cache from dh(1) and retrigger a rebuild of these variables.
446           This is useful in the very rare case where the package need to do
447           multiple builds but with different ...FLAGS options.  A concrete
448           example would be needing to change the -O parameter in CFLAGS in
449           the second build:
450
451               export DEB_CFLAGS_MAINT_APPEND=-O3
452
453               %:
454                   dh $@
455
456               override_dh_auto_configure:
457                   dh_auto_configure -Bbuild-deb ...
458                   DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
459                      --reload-all-buildenv-variables -Bbuild-udeb ...
460
461           Without --reload-all-buildenv-variables in the second call to
462           dh_auto_configure(1), the change in DEB_CFLAGS_MAINT_APPEND would
463           be ignored as dh_auto_configure(1) would use the cached value of
464           CFLAGS set by dh(1).
465
466           This option is only available with debhelper (>= 12.7~) when the
467           package uses compatibility level 9 or later.
468
469       --list, -l
470           List all build systems supported by debhelper on this system. The
471           list includes both default and third party build systems (marked as
472           such). Also shows which build system would be automatically
473           selected, or which one is manually specified with the --buildsystem
474           option.
475

COMPATIBILITY LEVELS

477       From time to time, major non-backwards-compatible changes need to be
478       made to debhelper, to keep it clean and well-designed as needs change
479       and its author gains more experience. To prevent such major changes
480       from breaking existing packages, the concept of debhelper compatibility
481       levels was introduced. You must tell debhelper which compatibility
482       level it should use, and it modifies its behavior in various ways.
483
484       In current debhelper, you can specify the compatibility level in
485       debian/control by adding a Build-Depends on the debhelper-compat
486       package.  For example, to use v12 mode, ensure debian/control has:
487
488         Build-Depends: debhelper-compat (= 12)
489
490       This also serves as an appropriate versioned build dependency on a
491       sufficient version of the debhelper package, so you do not need to
492       specify a separate versioned build dependency on the debhelper package
493       unless you need a specific point release of debhelper (such as for the
494       introduction of a new feature or bugfix within a compatibility level).
495
496       Note that debhelper does not provide debhelper-compat for experimental
497       or beta compatibility levels; packages experimenting with those
498       compatibility levels should use debian/compat or DH_COMPAT.
499
500       Prior versions of debhelper required specifying the compatibility level
501       in the file debian/compat, and current debhelper still supports this
502       for backward compatibility, though a package may not specify a
503       compatibility level via multiple methods at once. To use this method,
504       debian/compat should contain the compatibility level as a single
505       number, and no other content. If you specify the compatibility level by
506       this method, your package will also need a versioned build dependency
507       on a version of the debhelper package equal to (or greater than) the
508       compatibility level your package uses. So, if you specify compatibility
509       level 12 in debian/compat, ensure debian/control has:
510
511         Build-Depends: debhelper (>= 12~)
512
513       Unless otherwise indicated, all debhelper documentation assumes that
514       you are using the most recent compatibility level, and in most cases
515       does not indicate if the behavior is different in an earlier
516       compatibility level, so if you are not using the most recent
517       compatibility level, you're advised to read below for notes about what
518       is different in earlier compatibility levels.
519
520   Supported compatibility levels
521       These are the available compatibility levels:
522
523       v5  This is the lowest supported compatibility level.
524
525           If you are upgrading from an earlier compatibility level, please
526           review debhelper-obsolete-compat(7).
527
528           This mode is deprecated.
529
530       v6  Changes from v5 are:
531
532           -       Commands that generate maintainer script fragments will
533                   order the fragments in reverse order for the prerm and
534                   postrm scripts.
535
536           -       dh_installwm will install a slave manpage link for
537                   x-window-manager.1.gz, if it sees the man page in
538                   usr/share/man/man1 in the package build directory.
539
540           -       dh_builddeb did not previously delete everything matching
541                   DH_ALWAYS_EXCLUDE, if it was set to a list of things to
542                   exclude, such as CVS:.svn:.git. Now it does.
543
544           -       dh_installman allows overwriting existing man pages in the
545                   package build directory. In previous compatibility levels
546                   it silently refuses to do this.
547
548           This mode is deprecated.
549
550       v7  Changes from v6 are:
551
552           -       dh_install, will fall back to looking for files in
553                   debian/tmp if it doesn't find them in the current directory
554                   (or wherever you tell it look using --sourcedir). This
555                   allows dh_install to interoperate with dh_auto_install,
556                   which installs to debian/tmp, without needing any special
557                   parameters.
558
559           -       dh_clean will read debian/clean and delete files listed
560                   there.
561
562           -       dh_clean will delete toplevel *-stamp files.
563
564           -       dh_installchangelogs will guess at what file is the
565                   upstream changelog if none is specified.
566
567           This mode is deprecated.
568
569       v8  Changes from v7 are:
570
571           -       Commands will fail rather than warning when they are passed
572                   unknown options.
573
574           -       dh_makeshlibs will run dpkg-gensymbols on all shared
575                   libraries that it generates shlibs files for. So -X can be
576                   used to exclude libraries.  Also, libraries in unusual
577                   locations that dpkg-gensymbols would not have processed
578                   before will be passed to it, a behavior change that can
579                   cause some packages to fail to build.
580
581           -       dh requires the sequence to run be specified as the first
582                   parameter, and any switches come after it. Ie, use "dh $@
583                   --foo", not "dh --foo $@".
584
585           -       dh_auto_* prefer to use Perl's Module::Build in preference
586                   to Makefile.PL.
587
588           This mode is deprecated.
589
590       v9  Changes from v8 are:
591
592           -       Multiarch support. In particular, dh_auto_configure passes
593                   multiarch directories to autoconf in --libdir and
594                   --libexecdir.
595
596           -       dh is aware of the usual dependencies between targets in
597                   debian/rules.  So, "dh binary" will run any build, build-
598                   arch, build-indep, install, etc targets that exist in the
599                   rules file. There's no need to define an explicit binary
600                   target with explicit dependencies on the other targets.
601
602           -       dh_strip compresses debugging symbol files to reduce the
603                   installed size of -dbg packages.
604
605           -       dh_auto_configure does not include the source package name
606                   in --libexecdir when using autoconf.
607
608           -       dh does not default to enabling --with=python-support
609
610                   (Obsolete: As the dh_pysupport tool was removed from Debian
611                   stretch.  Since debhelper/10.3, dh no longer enables this
612                   sequence add-on regardless of compat level)
613
614           -       All of the dh_auto_* debhelper programs and dh set
615                   environment variables listed by dpkg-buildflags, unless
616                   they are already set.
617
618           -       dh_auto_configure passes dpkg-buildflags CFLAGS, CPPFLAGS,
619                   and LDFLAGS to perl Makefile.PL and Build.PL
620
621           -       dh_strip puts separated debug symbols in a location based
622                   on their build-id.
623
624           -       Executable debhelper config files are run and their output
625                   used as the configuration.
626
627       v10 Changes from v9 are:
628
629           -       dh_installinit will no longer install a file named
630                   debian/package as an init script.
631
632           -       dh_installdocs will error out if it detects links created
633                   with --link-doc between packages of architecture "all" and
634                   non-"all" as it breaks binNMUs.
635
636           -       dh_installdeb no longer installs a maintainer-provided
637                   debian/package.shlibs file.  This is now done by
638                   dh_makeshlibs instead.
639
640           -       dh_installwm refuses to create a broken package if no man
641                   page can be found (required to register for the x-window-
642                   manager alternative).
643
644           -       Debhelper will default to --parallel for all buildsystems
645                   that support parallel building.  This can be disabled by
646                   using either --no-parallel or passing --max-parallel with a
647                   value of 1.
648
649           -       The dh command will not accept any of the deprecated
650                   "manual sequence control" parameters (--before, --after,
651                   etc.).  Please use override targets instead.
652
653                   Retroactively applied to earlier compat levels: dh no
654                   longer accepts any of these since debhelper/12.4.
655
656           -       The dh command will no longer use log files to track which
657                   commands have been run.  The dh command still keeps track
658                   of whether it already ran the "build" sequence and skip it
659                   if it did.
660
661                   The main effects of this are:
662
663                   -   With this, it is now easier to debug the install or/and
664                       binary sequences because they can now trivially be re-
665                       run (without having to do a full "clean and rebuild"
666                       cycle)
667
668                   -   The main caveat is that dh_* now only keeps track of
669                       what happened in a single override target.  When all
670                       the calls to a given dh_cmd command happens in the same
671                       override target everything will work as before.
672
673                       Example of where it can go wrong:
674
675                         override_dh_foo:
676                           dh_foo -pmy-pkg
677
678                         override_dh_bar:
679                           dh_bar
680                           dh_foo --remaining
681
682                       In this case, the call to dh_foo --remaining will also
683                       include my-pkg, since dh_foo -pmy-pkg was run in a
684                       separate override target.  This issue is not limited to
685                       --remaining, but also includes -a, -i, etc.
686
687           -       The dh_installdeb command now shell-escapes the lines in
688                   the maintscript config file.  This was the original intent
689                   but it did not work properly and packages have begun to
690                   rely on the incomplete shell escaping (e.g. quoting file
691                   names).
692
693           -       The dh_installinit command now defaults to
694                   --restart-after-upgrade.  For packages needing the previous
695                   behaviour, please use --no-restart-after-upgrade.
696
697           -       The autoreconf sequence is now enabled by default.  Please
698                   pass --without autoreconf to dh if this is not desirable
699                   for a given package
700
701           -       The systemd sequence is now enabled by default.  Please
702                   pass --without systemd to dh if this is not desirable for a
703                   given package.
704
705           -       Retroactively removed: dh no longer creates the package
706                   build directory when skipping running debhelper commands.
707                   This will not affect packages that only build with
708                   debhelper commands, but it may expose bugs in commands not
709                   included in debhelper.
710
711                   This compatibility feature had a bug since its inception in
712                   debhelper/9.20130516 that made it fail to apply in compat 9
713                   and earlier.  As there has been no reports of issues caused
714                   by this bug in those ~5 years, this item have been removed
715                   rather than fixed.
716
717       v11 This mode is discouraged.
718
719           The compat 11 is discouraged for new packages as it suffers from
720           feature interaction between dh_installinit and dh_installsystemd
721           causing services to not run correctly in some cases.  Please
722           consider using compatibility mode 10 or 12 instead.  More details
723           about the issue are available in Debian#887904 and
724           <https://lists.debian.org/debian-release/2019/04/msg01442.html>.
725
726           Changes from v10 are:
727
728           -       dh_installinit no longer installs service or tmpfile files,
729                   nor generates maintainer scripts for those files.  Please
730                   use the new dh_installsystemd helper.
731
732           -       The dh_systemd_enable and dh_systemd_start helpers have
733                   been replaced by the new dh_installsystemd helper.  For the
734                   same reason, the systemd sequence for dh has also been
735                   removed.  If you need to disable the dh_installsystemd
736                   helper tool, please use an empty override target.
737
738                   Please note that the dh_installsystemd tool has a slightly
739                   different behaviour in some cases (e.g. when using the
740                   --name parameter).
741
742           -       dh_installdirs no longer creates debian/package directories
743                   unless explicitly requested (or it has to create a
744                   subdirectory in it).
745
746                   The vast majority of all packages will be unaffected by
747                   this change.
748
749           -       The makefile buildsystem now passes INSTALL="install
750                   --strip-program=true" to make(1).  Derivative buildsystems
751                   (e.g. configure or cmake) are unaffected by this change.
752
753           -       The autoconf buildsystem now passes --runstatedir=/run to
754                   ./configure.
755
756           -       The cmake buildsystem now passes
757                   -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
758
759           -       dh_installman will now prefer detecting the language from
760                   the path name rather than the extension.
761
762           -       dh_auto_install will now only create the destination
763                   directory it needs.  Previously, it would create the
764                   package build directory for all packages.  This will not
765                   affect packages that only build with debhelper commands,
766                   but it may expose bugs in commands not included in
767                   debhelper.
768
769           -       The helpers dh_installdocs, dh_installexamples,
770                   dh_installinfo, and dh_installman now error out if their
771                   config has a pattern that does not match anything or
772                   reference a path that does not exist.
773
774                   Known exceptions include building with the nodoc profile,
775                   where the above tools will silently permit failed matches
776                   where the patterns are used to specify documentation.
777
778           -       The helpers dh_installdocs, dh_installexamples,
779                   dh_installinfo, and dh_installman now accept the parameter
780                   --sourcedir with same meaning as dh_install. Furthermore,
781                   they now also fall back to debian/tmp like dh_install.
782
783                   Migration note: A bug in debhelper 11 up to 11.1.5 made
784                   dh_installinfo incorrectly ignore --sourcedir.
785
786           -       The perl-makemaker and perl-build build systems no longer
787                   pass -I. to perl.  Packages that still need this behaviour
788                   can emulate it by using the PERL5LIB environment variable.
789                   E.g. by adding export PERL5LIB=. in their debian/rules file
790                   (or similar).
791
792           -       The PERL_USE_UNSAFE_INC environment variable is no longer
793                   set by dh or any of the dh_auto_* tools.  It was added as a
794                   temporary work around to avoid a lot of packages failing to
795                   build at the same time.
796
797                   Note this item will eventually become obsolete as upstream
798                   intends to drop support for the PERL_USE_UNSAFE_INC
799                   environment variable.  When perl drops support for it, then
800                   this variable will be removed retroactively from existing
801                   compat levels as well.
802
803           -       The dh_makeshlibs helper will now exit with an error if
804                   objdump returns a non-zero exit from analysing a given
805                   file.
806
807           -       The dh_installdocs and dh_installexamples tools may now
808                   install most of the documentation in a different path to
809                   comply with the recommendation from Debian policy §12.3
810                   (since version 3.9.7).
811
812                   Note that if a given source package only contains a single
813                   binary package in debian/control or none of the packages
814                   are -doc packages, then this change is not relevant for
815                   that source package and you can skip to the next change.
816
817                   By default, these tools will now attempt to determine a
818                   "main package for the documentation" (called a doc-main-
819                   package from here on) for every -doc package.  If they find
820                   such a doc-main-package, they will now install the
821                   documentation into the path /usr/share/doc/doc-main-package
822                   in the given doc package.  I.e. the path can change but the
823                   documentation is still shipped in the -doc package.
824
825                   The --doc-main-package option can be used when the auto-
826                   detection is insufficient or to reset the path to its
827                   previous value if there is a reason to diverge from Debian
828                   policy recommendation.
829
830                   Some documentation will not be affected by this change.
831                   These exceptions include the copyright file, changelog
832                   files, README.Debian, etc.  These files will still be
833                   installed in the path /usr/share/doc/package.
834
835           -       The dh_strip and dh_shlibdeps tools no longer uses filename
836                   patterns to determine which files to process.  Instead,
837                   they open the file and look for an ELF header to determine
838                   if a given file is an shared object or an ELF executable.
839
840                   This change may cause the tools to process more files than
841                   previously.
842
843       v12 This is the recommended mode of operation.
844
845           Changes from v11 are:
846
847           -       The dh_makeshlibs tool now generates shlibs files with
848                   versioned dependency by default.  This means that
849                   -VUpstream-Version (a.k.a. -V) is now the default.
850
851                   If an unversioned dependency in the shlibs file is wanted,
852                   this can be obtained by passing -VNone instead.  However,
853                   please see dh_makeshlibs(1) for the caveat of unversioned
854                   dependencies.
855
856           -       The -s (--same-arch) option is removed.  Please use -a
857                   (--arch) instead.
858
859           -       Invoking dh_clean -k now causes an error instead of a
860                   deprecation warning.
861
862           -       The --no-restart-on-upgrade option in dh_installinit has
863                   been removed.  Please use the new name --no-stop-on-upgrade
864
865           -       There was a bug in the doit (and similar) functions from
866                   Debian::Debhelper::Dh_Lib that made them spawn a shell in
867                   one particular circumstance.  This bug is now removed and
868                   will cause helpers that rely on the bug to fail with a
869                   "command not found"-error.
870
871           -       The --list-missing and --fail-missing in dh_install has
872                   been removed.  Please use dh_missing and its corresponding
873                   options, which can also see the files installed by other
874                   helpers.
875
876           -       The dh_installinit helper no longer installs configuration
877                   for the upstart init system.  Instead, it will abort the
878                   build if it finds an old upstart configuration file.  The
879                   error is there to remind the package maintainer to ensure
880                   the proper removal of the conffiles shipped in previous
881                   versions of the package (if any).
882
883           -       The dh_installdeb tool will do basic validation of some
884                   dpkg-maintscript-helper(1) commands and will error out if
885                   the commands appear to be invalid.
886
887           -       The dh_missing tool will now default to --list-missing.
888
889           -       The dh_makeshlibs tool will now only pass libraries to
890                   dpkg-gensymbols(1) if the ELF binary has a SONAME
891                   (containing ".so").
892
893           -       The dh_compress tool no longer compresses examples (i.e.
894                   anything installed in </usr/share/doc/package/examples>.)
895
896           -       The standard sequence in dh now includes dh_dwz and
897                   dh_installinitramfs by default.  This makes the dwz and
898                   installinitramfs sequences obsolete and they will now fail
899                   with an error.  If you want to skip these commands, then
900                   please insert an empty override target for them in
901                   debian/rules (e.g. override_dh_dwz:)
902
903           -       The build systems meson and autoconf no longer explicitly
904                   set the --libexecdir variable and thus relies on the build
905                   system default - which should be /usr/libexec (per FHS 3.0,
906                   adopted in Debian Policy 4.1.5).
907
908                   If a particular upstream package does not use the correct
909                   default, the parameter can often be passed manually via
910                   dh_auto_configure(1).  E.g.  via the following example:
911
912                       override_dh_auto_configure:
913                           dh_auto_configure -- --libexecdir=/usr/libexec
914
915                   Note the -- before the --libexecdir parameter.
916
917           -       The dh_installdeb tool no longer installs the maintainer
918                   provided conffiles file.  The file has mostly been obsolete
919                   since compatibility level 3, where dh_installdeb began to
920                   automatically compute the resulting conffiles control file.
921
922           -       The dh_installsystemd tool no longer relies on
923                   dh_installinit for handling systemd services that have a
924                   sysvinit alternative.  Both tools must now be used in such
925                   a case to ensure the service is properly started under both
926                   sysvinit and systemd.
927
928                   If you have an override for dh_installinit (e.g. to call it
929                   with --no-start) then you will probably need one for
930                   dh_installsystemd as well now.
931
932                   This change makes dh_installinit inject a misc:Pre-Depends
933                   for init-system-helpers (>= 1.54~).  Please ensure that the
934                   package lists ${misc:Pre-Depends} in its Pre-Depends field
935                   before upgrading to compat 12.
936
937           -       The third-party dh_golang tool (from dh-golang package) now
938                   defaults on honoring DH_GOLANG_EXCLUDES variable for source
939                   installation in -dev packages and not only during the
940                   building process. Please set DH_GOLANG_EXCLUDES_ALL to
941                   false to revert to the previous behaviour. See
942                   Debian::Debhelper::Buildsystem::golang(3pm) for details and
943                   examples.
944
945           -       dh_installsystemduser is now included in the dh standard
946                   sequence by default.
947
948           -       The python-distutils buildsystem is now removed.  Please
949                   use the third-party build system pybuild instead.
950
951       v13 This compatibility level is still open for development; use with
952           caution.
953
954           Changes from v12 are:
955
956           -       The meson+ninja build system now uses meson test instead of
957                   ninja test when running the test suite.  Any override of
958                   dh_auto_test that passes extra parameters to upstream test
959                   runner should be reviewed as meson test is not command line
960                   compatible with ninja test.
961
962           -       All debhelper like tools based on the official debhelper
963                   library (including dh and the official dh_* tools) no
964                   longer accepts abbreviated command parameters.  At the same
965                   time, dh now optimizes out calls to redundant dh_* helpers
966                   even when passed long command line options.
967
968           -       The ELF related debhelper tools (dh_dwz, dh_strip,
969                   dh_makeshlibs, dh_shlibdeps) are now only run for arch
970                   dependent packages by default (i.e. they are excluded from
971                   *-indep targets and are passed -a by default).
972
973                   If you need them for *-indep targets, you can add an
974                   explicit Build-Depends on dh-sequence-elf-tools.
975
976           -       The third-party gradle build system (from gradle-debian-
977                   helper package) now runs the upstream-provided test suite
978                   automatically.  To suppress such behavior, override
979                   dh_auto_test.
980
981           -       The dh_installman tool now aborts if it sees conflicting
982                   definitions of a manpage.  This typically happens if the
983                   upstream build system is installing a compressed version
984                   and the package lists an uncompressed version of the
985                   manpage in debian/package.manpages.  Often the easiest fix
986                   is to remove the manpage from debian/package.manpages
987                   (assuming both version are identical).
988
989           -       The dh_auto_* helpers now resets the environment variables
990                   HOME and common XDG_* variable.  HOME and XDG_RUNTIME_DIR
991                   are each set to a distinct writable directory. The rest of
992                   the environment variables are cleared.
993

NOTES

995   Multiple binary package support
996       If your source package generates more than one binary package,
997       debhelper programs will default to acting on all binary packages when
998       run. If your source package happens to generate one architecture
999       dependent package, and another architecture independent package, this
1000       is not the correct behavior, because you need to generate the
1001       architecture dependent packages in the binary-arch debian/rules target,
1002       and the architecture independent packages in the binary-indep
1003       debian/rules target.
1004
1005       To facilitate this, as well as give you more control over which
1006       packages are acted on by debhelper programs, all debhelper programs
1007       accept the -a, -i, -p, and -s parameters. These parameters are
1008       cumulative.  If none are given, debhelper programs default to acting on
1009       all packages listed in the control file, with the exceptions below.
1010
1011       First, any package whose Architecture field in debian/control does not
1012       match the DEB_HOST_ARCH architecture will be excluded ("Debian Policy,
1013       section 5.6.8").
1014
1015       Also, some additional packages may be excluded based on the contents of
1016       the DEB_BUILD_PROFILES environment variable and Build-Profiles fields
1017       in binary package stanzas in debian/control, according to the draft
1018       policy at <https://wiki.debian.org/BuildProfileSpec>.
1019
1020       Interaction between package selections and Build-Profiles
1021
1022       Build-Profiles affect which packages are included in the package
1023       selections mechanisms in debhelper.  Generally, the package selections
1024       are described from the assumption that all packages are enabled.  This
1025       section describes how the selections react when a package is disabled
1026       due to the active Build-Profiles (or lack of active Build-Profiles).
1027
1028       -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)
1029           The package disabled by Build-Profiles is silently excluded from
1030           the selection.
1031
1032           Note you will receive a warning if all packages related to these
1033           selections are disabled.  In that case, it generally does not make
1034           sense to do the build in the first place.
1035
1036       -N package / --no-package package
1037           The option is accepted and effectively does nothing.
1038
1039       -p package / --package package
1040           The option is accepted, but debhelper will not act on the package.
1041
1042       Note that it does not matter whether a package is enabled or disabled
1043       by default.
1044
1045   Automatic generation of Debian install scripts
1046       Some debhelper commands will automatically generate parts of Debian
1047       maintainer scripts. If you want these automatically generated things
1048       included in your existing Debian maintainer scripts, then you need to
1049       add #DEBHELPER# to your scripts, in the place the code should be added.
1050       #DEBHELPER# will be replaced by any auto-generated code when you run
1051       dh_installdeb.
1052
1053       If a script does not exist at all and debhelper needs to add something
1054       to it, then debhelper will create the complete script.
1055
1056       All debhelper commands that automatically generate code in this way let
1057       it be disabled by the -n parameter (see above).
1058
1059       Note that the inserted code will be shell code, so you cannot directly
1060       use it in a Perl script. If you would like to embed it into a Perl
1061       script, here is one way to do that (note that I made sure that $1, $2,
1062       etc are set with the set command):
1063
1064         my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
1065         #DEBHELPER#
1066         EOF
1067         if (system($temp)) {
1068            my $exit_code = ($? >> 8) & 0xff;
1069            my $signal = $? & 0x7f;
1070            if ($exit_code) {
1071                die("The debhelper script failed with error code: ${exit_code}");
1072            } else {
1073                die("The debhelper script was killed by signal: ${signal}");
1074            }
1075         }
1076
1077   Automatic generation of miscellaneous dependencies.
1078       Some debhelper commands may make the generated package need to depend
1079       on some other packages. For example, if you use dh_installdebconf(1),
1080       your package will generally need to depend on debconf. Or if you use
1081       dh_installxfonts(1), your package will generally need to depend on a
1082       particular version of xutils. Keeping track of these miscellaneous
1083       dependencies can be annoying since they are dependent on how debhelper
1084       does things, so debhelper offers a way to automate it.
1085
1086       All commands of this type, besides documenting what dependencies may be
1087       needed on their man pages, will automatically generate a substvar
1088       called ${misc:Depends}. If you put that token into your debian/control
1089       file, it will be expanded to the dependencies debhelper figures you
1090       need.
1091
1092       This is entirely independent of the standard ${shlibs:Depends}
1093       generated by dh_makeshlibs(1), and the ${perl:Depends} generated by
1094       dh_perl(1).  You can choose not to use any of these, if debhelper's
1095       guesses don't match reality.
1096
1097   Package build directories
1098       By default, all debhelper programs assume that the temporary directory
1099       used for assembling the tree of files in a package is debian/package.
1100
1101       Sometimes, you might want to use some other temporary directory. This
1102       is supported by the -P flag. For example, "dh_installdocs
1103       -Pdebian/tmp", will use debian/tmp as the temporary directory. Note
1104       that if you use -P, the debhelper programs can only be acting on a
1105       single package at a time. So if you have a package that builds many
1106       binary packages, you will need to also use the -p flag to specify which
1107       binary package the debhelper program will act on.
1108
1109   udebs
1110       Debhelper includes support for udebs. To create a udeb with debhelper,
1111       add "Package-Type: udeb" to the package's stanza in debian/control.
1112       Debhelper will try to create udebs that comply with debian-installer
1113       policy, by making the generated package files end in .udeb, not
1114       installing any documentation into a udeb, skipping over preinst,
1115       postrm, prerm, and config scripts, etc.
1116

ENVIRONMENT

1118       The following environment variables can influence the behavior of
1119       debhelper.  It is important to note that these must be actual
1120       environment variables in order to function properly (not simply
1121       Makefile variables). To specify them properly in debian/rules, be sure
1122       to "export" them. For example, "export DH_VERBOSE".
1123
1124       DH_VERBOSE
1125           Set to 1 to enable verbose mode. Debhelper will output every
1126           command it runs. Also enables verbose build logs for some build
1127           systems like autoconf.
1128
1129       DH_QUIET
1130           Set to 1 to enable quiet mode. Debhelper will not output commands
1131           calling the upstream build system nor will dh print which
1132           subcommands are called and depending on the upstream build system
1133           might make that more quiet, too.  This makes it easier to spot
1134           important messages but makes the output quite useless as buildd
1135           log.  Ignored if DH_VERBOSE is also set.
1136
1137       DH_COMPAT
1138           Temporarily specifies what compatibility level debhelper should run
1139           at, overriding any value specified via Build-Depends on debhelper-
1140           compat or via the debian/compat file.
1141
1142       DH_NO_ACT
1143           Set to 1 to enable no-act mode.
1144
1145       DH_OPTIONS
1146           Anything in this variable will be prepended to the command line
1147           arguments of all debhelper commands.
1148
1149           When using dh(1), it can be passed options that will be passed on
1150           to each debhelper command, which is generally better than using
1151           DH_OPTIONS.
1152
1153       DH_ALWAYS_EXCLUDE
1154           If set, this adds the value the variable is set to to the -X
1155           options of all commands that support the -X option. Moreover,
1156           dh_builddeb will rm -rf anything that matches the value in your
1157           package build tree.
1158
1159           This can be useful if you are doing a build from a CVS source tree,
1160           in which case setting DH_ALWAYS_EXCLUDE=CVS will prevent any CVS
1161           directories from sneaking into the package you build. Or, if a
1162           package has a source tarball that (unwisely) includes CVS
1163           directories, you might want to export DH_ALWAYS_EXCLUDE=CVS in
1164           debian/rules, to make it take effect wherever your package is
1165           built.
1166
1167           Multiple things to exclude can be separated with colons, as in
1168           DH_ALWAYS_EXCLUDE=CVS:.svn
1169
1170       DH_EXTRA_ADDONS
1171           If set, this adds the specified dh addons to be run in the
1172           appropriate places in the sequence of commands. This is equivalent
1173           to specifying the addon to run with the --with flag in the
1174           debian/rules file. Any --without calls specifying an addon in this
1175           environment variable will not be run.
1176
1177           This is intended to be used by downstreams or specific local
1178           configurations that require a debhelper addon to be run during
1179           multiple builds without having to patch a large number of rules
1180           file. If at all possible, this should be avoided in favor of a
1181           --with flag in the rules file.
1182
1183       CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS,
1184       FCFLAGS, LDFLAGS
1185           By default (in any non-deprecated compat level), debhelper will
1186           automatically set these flags by using dpkg-buildflags(1), when
1187           they are unset.  If you need to change the default flags, please
1188           use the features from dpkg-buildflags(1) to do this (e.g.
1189           DEB_BUILD_MAINT_OPTIONS=hardening=all or
1190           DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true) rather than setting
1191           the concrete variable directly.
1192
1193       HOME, XDG_*
1194           In compat 13 and later, these environment variables are reset
1195           before invoking the upstream build system via the dh_auto_*
1196           helpers.  The variables HOME and XDG_RUNTIME_DIR will be set to a
1197           writable directory. The remaining variables will be cleared.
1198
1199           The directories will be created as empty directories but they will
1200           be reused between calls to dh_auto_*.  Any content will persist
1201           until explicitly deleted or dh_clean.
1202

SEE ALSO

1204       /usr/share/doc/debhelper/examples/
1205           A set of example debian/rules files that use debhelper.
1206
1207       <http://joeyh.name/code/debhelper/>
1208           Debhelper web site.
1209

AUTHOR

1211       Joey Hess <joeyh@debian.org>
1212
1213
1214
121512.7.3                            2020-07-27                      debhelper(7)
Impressum