1debhelper(7) Debhelper debhelper(7)
2
6 debhelper - the debhelper tool suite
7
9 dh_* [-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]
10
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 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 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 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
38 Here is the list of debhelper commands you can use. See their man pages
39 for additional documentation.
40 dh_auto_build(1)
42 automatically builds a package
43 dh_auto_clean(1)
45 automatically cleans up after a build
46 dh_auto_configure(1)
48 automatically configure a package prior to building
49 dh_auto_install(1)
51 automatically runs make install or similar
52 dh_auto_test(1)
54 automatically runs a package's test suites
55 dh_bugfiles(1)
57 install bug reporting customization files into package build
58 directories
59 dh_builddeb(1)
61 build Debian binary packages
62 dh_clean(1)
64 clean up package build directories
65 dh_compress(1)
67 compress files and fix symlinks in package build directories
68 dh_dwz(1)
70 optimize DWARF debug information in ELF binaries via dwz
71 dh_fixperms(1)
73 fix permissions of files in package build directories
74 dh_gencontrol(1)
76 generate and install control file
77 dh_icons(1)
79 Update caches of Freedesktop icons
80 dh_install(1)
82 install files into package build directories
83 dh_installcatalogs(1)
85 install and register SGML Catalogs
86 dh_installchangelogs(1)
88 install changelogs into package build directories
89 dh_installcron(1)
91 install cron scripts into etc/cron.*
92 dh_installdeb(1)
94 install files into the DEBIAN directory
95 dh_installdebconf(1)
97 install files used by debconf in package build directories
98 dh_installdirs(1)
100 create subdirectories in package build directories
101 dh_installdocs(1)
103 install documentation into package build directories
104 dh_installemacsen(1)
106 register an Emacs add on package
107 dh_installexamples(1)
109 install example files into package build directories
110 dh_installgsettings(1)
112 install GSettings overrides and set dependencies
113 dh_installifupdown(1)
115 install if-up and if-down hooks
116 dh_installinfo(1)
118 install info files
119 dh_installinit(1)
121 install service init files into package build directories
122 dh_installinitramfs(1)
124 install initramfs hooks and setup maintscripts
125 dh_installlogcheck(1)
127 install logcheck rulefiles into etc/logcheck/
128 dh_installlogrotate(1)
130 install logrotate config files
131 dh_installman(1)
133 install man pages into package build directories
134 dh_installmenu(1)
136 install Debian menu files into package build directories
137 dh_installmime(1)
139 install mime files into package build directories
140 dh_installmodules(1)
142 register kernel modules
143 dh_installpam(1)
145 install pam support files
146 dh_installppp(1)
148 install ppp ip-up and ip-down files
149 dh_installsystemd(1)
151 install systemd unit files
152 dh_installsystemduser(1)
154 install systemd unit files
155 dh_installudev(1)
157 install udev rules files
158 dh_installwm(1)
160 register a window manager
161 dh_installxfonts(1)
163 register X fonts
164 dh_link(1)
166 create symlinks in package build directories
167 dh_lintian(1)
169 install lintian override files into package build directories
170 dh_listpackages(1)
172 list binary packages debhelper will act on
173 dh_makeshlibs(1)
175 automatically create shlibs file and call dpkg-gensymbols
176 dh_md5sums(1)
178 generate DEBIAN/md5sums file
179 dh_missing(1)
181 check for missing files
182 dh_movefiles(1)
184 move files out of debian/tmp into subpackages
185 dh_perl(1)
187 calculates Perl dependencies and cleans up after MakeMaker
188 dh_prep(1)
190 perform cleanups in preparation for building a binary package
191 dh_shlibdeps(1)
193 calculate shared library dependencies
194 dh_strip(1)
196 strip executables, shared libraries, and some static libraries
197 dh_systemd_enable(1)
199 enable/disable systemd unit files
200 dh_systemd_start(1)
202 start/stop/restart systemd unit files
203 dh_testdir(1)
205 test directory before building Debian package
206 dh_testroot(1)
208 ensure that a package is built with necessary level of root
209 permissions
210 dh_ucf(1)
212 register configuration files with ucf
213 dh_update_autotools_config(1)
215 Update autotools config files
216 dh_usrlocal(1)
218 migrate usr/local directories to maintainer scripts
219 Deprecated Commands
221 A few debhelper commands are deprecated and should not be used.
222 dh_gconf(1)
224 install GConf defaults files and register schemas (deprecated)
225 dh_installmanpages(1)
227 old-style man page installer (deprecated)
228 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
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 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 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 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 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 The syntax of these files is intentionally kept very simple to make
272 them easy to read, understand, and modify.
273 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 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 When using executable debhelper config files, please be aware of the
285 following:
286 · The executable config file must exit with success (i.e. its return
288 code should indicate success).
289 · The output will be used exactly as it is. Notably, debhelper will
291 not expand wildcards or strip comments in the output.
292 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
298 The following command line options are supported by all debhelper
299 programs.
300 -v, --verbose
302 Verbose mode: show all commands that modify the package build
303 directory.
304 --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 -a, --arch
310 Act on architecture dependent packages that should be built for the
311 DEB_HOST_ARCH architecture.
312 -i, --indep
314 Act on all architecture independent packages.
315 -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 -s, --same-arch
322 Deprecated alias of -a.
323 This option is removed in compat 12.
325 -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 --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 --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 For example, if upstream ships a debian/init that you don't want
346 dh_installinit to install, use --ignore=debian/init
347 -Ptmpdir, --tmpdir=tmpdir
349 Use tmpdir for package build directory. The default is
350 debian/package
351 --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 -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
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 -n Do not modify postinst, postrm, etc. scripts.
371 -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 -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
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 -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 -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 -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 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 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 --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 If neither option is specified, debhelper currently defaults to
422 --parallel in compat 10 (or later) and --no-parallel otherwise.
423 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 --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 Notably, setting the maximum to 1 is effectively the same as using
437 --no-parallel.
438 --list, -l
440 List all build systems supported by debhelper on this system. The
441 list includes both default and third party build systems (marked as
442 such). Also shows which build system would be automatically
443 selected, or which one is manually specified with the --buildsystem
444 option.
445
447 From time to time, major non-backwards-compatible changes need to be
448 made to debhelper, to keep it clean and well-designed as needs change
449 and its author gains more experience. To prevent such major changes
450 from breaking existing packages, the concept of debhelper compatibility
451 levels was introduced. You must tell debhelper which compatibility
452 level it should use, and it modifies its behavior in various ways.
453 In current debhelper, you can specify the compatibility level in
455 debian/control by adding a Build-Depends on the debhelper-compat
456 package. For example, to use v12 mode, ensure debian/control has:
457 Build-Depends: debhelper-compat (= 12)
459 This also serves as an appropriate versioned build dependency on a
461 sufficient version of the debhelper package, so you do not need to
462 specify a separate versioned build dependency on the debhelper package
463 unless you need a specific point release of debhelper (such as for the
464 introduction of a new feature or bugfix within a compatibility level).
465 Note that debhelper does not provide debhelper-compat for experimental
467 or beta compatibility levels; packages experimenting with those
468 compatibility levels should use debian/compat or DH_COMPAT.
469 Prior versions of debhelper required specifying the compatibility level
471 in the file debian/compat, and current debhelper still supports this
472 for backward compatibility, though a package may not specify a
473 compatibility level via multiple methods at once. To use this method,
474 debian/compat should contain the compatibility level as a single
475 number, and no other content. If you specify the compatibility level by
476 this method, your package will also need a versioned build dependency
477 on a version of the debhelper package equal to (or greater than) the
478 compatibility level your package uses. So, if you specify compatibility
479 level 12 in debian/compat, ensure debian/control has:
480 Build-Depends: debhelper (>= 12~)
482 Unless otherwise indicated, all debhelper documentation assumes that
484 you are using the most recent compatibility level, and in most cases
485 does not indicate if the behavior is different in an earlier
486 compatibility level, so if you are not using the most recent
487 compatibility level, you're advised to read below for notes about what
488 is different in earlier compatibility levels.
489 Supported compatibility levels
491 These are the available compatibility levels:
492 v5 This is the lowest supported compatibility level.
494 If you are upgrading from an earlier compatibility level, please
496 review debhelper-obsolete-compat(7).
497 This mode is deprecated.
499 v6 Changes from v5 are:
501 - Commands that generate maintainer script fragments will
503 order the fragments in reverse order for the prerm and
504 postrm scripts.
505 - dh_installwm will install a slave manpage link for
507 x-window-manager.1.gz, if it sees the man page in
508 usr/share/man/man1 in the package build directory.
509 - dh_builddeb did not previously delete everything matching
511 DH_ALWAYS_EXCLUDE, if it was set to a list of things to
512 exclude, such as CVS:.svn:.git. Now it does.
513 - dh_installman allows overwriting existing man pages in the
515 package build directory. In previous compatibility levels
516 it silently refuses to do this.
517 This mode is deprecated.
519 v7 Changes from v6 are:
521 - dh_install, will fall back to looking for files in
523 debian/tmp if it doesn't find them in the current directory
524 (or wherever you tell it look using --sourcedir). This
525 allows dh_install to interoperate with dh_auto_install,
526 which installs to debian/tmp, without needing any special
527 parameters.
528 - dh_clean will read debian/clean and delete files listed
530 there.
531 - dh_clean will delete toplevel *-stamp files.
533 - dh_installchangelogs will guess at what file is the
535 upstream changelog if none is specified.
536 This mode is deprecated.
538 v8 Changes from v7 are:
540 - Commands will fail rather than warning when they are passed
542 unknown options.
543 - dh_makeshlibs will run dpkg-gensymbols on all shared
545 libraries that it generates shlibs files for. So -X can be
546 used to exclude libraries. Also, libraries in unusual
547 locations that dpkg-gensymbols would not have processed
548 before will be passed to it, a behavior change that can
549 cause some packages to fail to build.
550 - dh requires the sequence to run be specified as the first
552 parameter, and any switches come after it. Ie, use "dh $@
553 --foo", not "dh --foo $@".
554 - dh_auto_* prefer to use Perl's Module::Build in preference
556 to Makefile.PL.
557 This mode is deprecated.
559 v9 Changes from v8 are:
561 - Multiarch support. In particular, dh_auto_configure passes
563 multiarch directories to autoconf in --libdir and
564 --libexecdir.
565 - dh is aware of the usual dependencies between targets in
567 debian/rules. So, "dh binary" will run any build, build-
568 arch, build-indep, install, etc targets that exist in the
569 rules file. There's no need to define an explicit binary
570 target with explicit dependencies on the other targets.
571 - dh_strip compresses debugging symbol files to reduce the
573 installed size of -dbg packages.
574 - dh_auto_configure does not include the source package name
576 in --libexecdir when using autoconf.
577 - dh does not default to enabling --with=python-support
579 (Obsolete: As the dh_pysupport tool was removed from Debian
581 stretch. Since debhelper/10.3, dh no longer enables this
582 sequence add-on regardless of compat level)
583 - All of the dh_auto_* debhelper programs and dh set
585 environment variables listed by dpkg-buildflags, unless
586 they are already set.
587 - dh_auto_configure passes dpkg-buildflags CFLAGS, CPPFLAGS,
589 and LDFLAGS to perl Makefile.PL and Build.PL
590 - dh_strip puts separated debug symbols in a location based
592 on their build-id.
593 - Executable debhelper config files are run and their output
595 used as the configuration.
596 v10 Changes from v9 are:
598 - dh_installinit will no longer install a file named
600 debian/package as an init script.
601 - dh_installdocs will error out if it detects links created
603 with --link-doc between packages of architecture "all" and
604 non-"all" as it breaks binNMUs.
605 - dh_installdeb no longer installs a maintainer-provided
607 debian/package.shlibs file. This is now done by
608 dh_makeshlibs instead.
609 - dh_installwm refuses to create a broken package if no man
611 page can be found (required to register for the x-window-
612 manager alternative).
613 - Debhelper will default to --parallel for all buildsystems
615 that support parallel building. This can be disabled by
616 using either --no-parallel or passing --max-parallel with a
617 value of 1.
618 - The dh command will not accept any of the deprecated
620 "manual sequence control" parameters (--before, --after,
621 etc.). Please use override targets instead.
622 Retroactively applied to earlier compat levels: dh no
624 longer accepts any of these since debhelper/12.4.
625 - The dh command will no longer use log files to track which
627 commands have been run. The dh command still keeps track
628 of whether it already ran the "build" sequence and skip it
629 if it did.
630 The main effects of this are:
632 - With this, it is now easier to debug the install or/and
634 binary sequences because they can now trivially be re-
635 run (without having to do a full "clean and rebuild"
636 cycle)
637 - The main caveat is that dh_* now only keeps track of
639 what happened in a single override target. When all
640 the calls to a given dh_cmd command happens in the same
641 override target everything will work as before.
642 Example of where it can go wrong:
644 override_dh_foo:
646 dh_foo -pmy-pkg
647 override_dh_bar:
649 dh_bar
650 dh_foo --remaining
651 In this case, the call to dh_foo --remaining will also
653 include my-pkg, since dh_foo -pmy-pkg was run in a
654 separate override target. This issue is not limited to
655 --remaining, but also includes -a, -i, etc.
656 - The dh_installdeb command now shell-escapes the lines in
658 the maintscript config file. This was the original intent
659 but it did not work properly and packages have begun to
660 rely on the incomplete shell escaping (e.g. quoting file
661 names).
662 - The dh_installinit command now defaults to
664 --restart-after-upgrade. For packages needing the previous
665 behaviour, please use --no-restart-after-upgrade.
666 - The autoreconf sequence is now enabled by default. Please
668 pass --without autoreconf to dh if this is not desirable
669 for a given package
670 - The systemd sequence is now enabled by default. Please
672 pass --without systemd to dh if this is not desirable for a
673 given package.
674 - Retroactively removed: dh no longer creates the package
676 build directory when skipping running debhelper commands.
677 This will not affect packages that only build with
678 debhelper commands, but it may expose bugs in commands not
679 included in debhelper.
680 This compatibility feature had a bug since its inception in
682 debhelper/9.20130516 that made it fail to apply in compat 9
683 and earlier. As there has been no reports of issues caused
684 by this bug in those ~5 years, this item have been removed
685 rather than fixed.
686 v11 Changes from v10 are:
688 - dh_installinit no longer installs service or tmpfile files,
690 nor generates maintainer scripts for those files. Please
691 use the new dh_installsystemd helper.
692 - The dh_systemd_enable and dh_systemd_start helpers have
694 been replaced by the new dh_installsystemd helper. For the
695 same reason, the systemd sequence for dh has also been
696 removed. If you need to disable the dh_installsystemd
697 helper tool, please use an empty override target.
698 Please note that the dh_installsystemd tool has a slightly
700 different behaviour in some cases (e.g. when using the
701 --name parameter).
702 - dh_installdirs no longer creates debian/package directories
704 unless explicitly requested (or it has to create a
705 subdirectory in it).
706 The vast majority of all packages will be unaffected by
708 this change.
709 - The makefile buildsystem now passes INSTALL="install
711 --strip-program=true" to make(1). Derivative buildsystems
712 (e.g. configure or cmake) are unaffected by this change.
713 - The autoconf buildsystem now passes --runstatedir=/run to
715 ./configure.
716 - The cmake buildsystem now passes
718 -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
719 - dh_installman will now prefer detecting the language from
721 the path name rather than the extension.
722 - dh_auto_install will now only create the destination
724 directory it needs. Previously, it would create the
725 package build directory for all packages. This will not
726 affect packages that only build with debhelper commands,
727 but it may expose bugs in commands not included in
728 debhelper.
729 - The helpers dh_installdocs, dh_installexamples,
731 dh_installinfo, and dh_installman now error out if their
732 config has a pattern that does not match anything or
733 reference a path that does not exist.
734 Known exceptions include building with the nodoc profile,
736 where the above tools will silently permit failed matches
737 where the patterns are used to specify documentation.
738 - The helpers dh_installdocs, dh_installexamples,
740 dh_installinfo, and dh_installman now accept the parameter
741 --sourcedir with same meaning as dh_install. Furthermore,
742 they now also fall back to debian/tmp like dh_install.
743 Migration note: A bug in debhelper 11 up to 11.1.5 made
745 dh_installinfo incorrectly ignore --sourcedir.
746 - The perl-makemaker and perl-build build systems no longer
748 pass -I. to perl. Packages that still need this behaviour
749 can emulate it by using the PERL5LIB environment variable.
750 E.g. by adding export PERL5LIB=. in their debian/rules file
751 (or similar).
752 - The PERL_USE_UNSAFE_INC environment variable is no longer
754 set by dh or any of the dh_auto_* tools. It was added as a
755 temporary work around to avoid a lot of packages failing to
756 build at the same time.
757 Note this item will eventually become obsolete as upstream
759 intends to drop support for the PERL_USE_UNSAFE_INC
760 environment variable. When perl drops support for it, then
761 this variable will be removed retroactively from existing
762 compat levels as well.
763 - The dh_makeshlibs helper will now exit with an error if
765 objdump returns a non-zero exit from analysing a given
766 file.
767 - The dh_installdocs and dh_installexamples tools may now
769 install most of the documentation in a different path to
770 comply with the recommendation from Debian policy §12.3
771 (since version 3.9.7).
772 Note that if a given source package only contains a single
774 binary package in debian/control or none of the packages
775 are -doc packages, then this change is not relevant for
776 that source package and you can skip to the next change.
777 By default, these tools will now attempt to determine a
779 "main package for the documentation" (called a doc-main-
780 package from here on) for every -doc package. If they find
781 such a doc-main-package, they will now install the
782 documentation into the path /usr/share/doc/doc-main-package
783 in the given doc package. I.e. the path can change but the
784 documentation is still shipped in the -doc package.
785 The --doc-main-package option can be used when the auto-
787 detection is insufficient or to reset the path to its
788 previous value if there is a reason to diverge from Debian
789 policy recommendation.
790 Some documentation will not be affected by this change.
792 These exceptions include the copyright file, changelog
793 files, README.Debian, etc. These files will still be
794 installed in the path /usr/share/doc/package.
795 - The dh_strip and dh_shlibdeps tools no longer uses filename
797 patterns to determine which files to process. Instead,
798 they open the file and look for an ELF header to determine
799 if a given file is an shared object or an ELF executable.
800 This change may cause the tools to process more files than
802 previously.
803 v12 This is the recommended mode of operation.
805 Changes from v11 are:
807 - The dh_makeshlibs tool now generates shlibs files with
809 versioned dependency by default. This means that
810 -VUpstream-Version (a.k.a. -V) is now the default.
811 If an unversioned dependency in the shlibs file is wanted,
813 this can be obtained by passing -VNone instead. However,
814 please see dh_makeshlibs(1) for the caveat of unversioned
815 dependencies.
816 - The -s (--same-arch) option is removed. Please use -a
818 (--arch) instead.
819 - Invoking dh_clean -k now causes an error instead of a
821 deprecation warning.
822 - The --no-restart-on-upgrade option in dh_installinit has
824 been removed. Please use the new name --no-stop-on-upgrade
825 - There was a bug in the doit (and similar) functions from
827 Debian::Debhelper::Dh_Lib that made them spawn a shell in
828 one particular circumstance. This bug is now removed and
829 will cause helpers that rely on the bug to fail with a
830 "command not found"-error.
831 - The --list-missing and --fail-missing in dh_install has
833 been removed. Please use dh_missing and its corresponding
834 options, which can also see the files installed by other
835 helpers.
836 - The dh_installinit helper no longer installs configuration
838 for the upstart init system. Instead, it will abort the
839 build if it finds an old upstart configuration file. The
840 error is there to remind the package maintainer to ensure
841 the proper removal of the conffiles shipped in previous
842 versions of the package (if any).
843 - The dh_installdeb tool will do basic validation of some
845 dpkg-maintscript-helper(1) commands and will error out if
846 the commands appear to be invalid.
847 - The dh_missing tool will now default to --list-missing.
849 - The dh_makeshlibs tool will now only pass libraries to
851 dpkg-gensymbols(1) if the ELF binary has a SONAME
852 (containing ".so").
853 - The dh_compress tool no longer compresses examples (i.e.
855 anything installed in </usr/share/doc/package/examples>.)
856 - The standard sequence in dh now includes dh_dwz and
858 dh_installinitramfs by default. This makes the dwz and
859 installinitramfs sequences obsolete and they will now fail
860 with an error. If you want to skip these commands, then
861 please insert an empty override target for them in
862 debian/rules (e.g. override_dh_dwz:)
863 - The build systems meson and autoconf no longer explicitly
865 set the --libexecdir variable and thus relies on the build
866 system default - which should be /usr/libexec (per FHS 3.0,
867 adopted in Debian Policy 4.1.5).
868 If a particular upstream package does not use the correct
870 default, the parameter can often be passed manually via
871 dh_auto_configure(1). E.g. via the following example:
872 override_dh_auto_configure:
874 dh_auto_configure -- --libexecdir=/usr/libexec
875 Note the -- before the --libexecdir parameter.
877 - The dh_installdeb tool no longer installs the maintainer
879 provided conffiles file. The file has mostly been obsolete
880 since compatibility level 3, where dh_installdeb began to
881 automatically compute the resulting conffiles control file.
882 - The dh_installsystemd tool no longer relies on
884 dh_installinit for handling systemd services that have a
885 sysvinit alternative. Both tools must now be used in such
886 a case to ensure the service is properly started under both
887 sysvinit and systemd.
888 If you have an override for dh_installinit (e.g. to call it
890 with --no-start) then you will probably need one for
891 dh_installsystemd as well now.
892 This change makes dh_installinit inject a misc:Pre-Depends
894 for init-system-helpers (>= 1.54~). Please ensure that the
895 package lists ${misc:Pre-Depends} in its Pre-Depends field
896 before upgrading to compat 12.
897 - The third-party dh_golang tool (from dh-golang package) now
899 defaults on honoring DH_GOLANG_EXCLUDES variable for source
900 installation in -dev packages and not only during the
901 building process. Please set DH_GOLANG_EXCLUDES_ALL to
902 false to revert to the previous behaviour. See
903 Debian::Debhelper::Buildsystem::golang(3pm) for details and
904 examples.
905 - dh_installsystemduser is now included in the dh standard
907 sequence by default.
908 - The python-distutils buildsystem is now removed. Please
910 use the third-party build system pybuild instead.
911 v13 This compatibility level is still open for development; use with
913 caution.
914 Changes from v12 are:
916 - The meson+ninja build system now uses meson test instead of
918 ninja test when running the test suite. Any override of
919 dh_auto_test that passes extra parameters to upstream test
920 runner should be reviewed as meson test is not command line
921 compatible with ninja test.
922 - All debhelper like tools based on the official debhelper
924 library (including dh and the official dh_* tools) no
925 longer accepts abbreviated command parameters. At the same
926 time, dh now optimizes out calls to redundant dh_* helpers
927 even when passed long command line options.
928 - The ELF related debhelper tools (dh_dwz, dh_strip,
930 dh_makeshlibs, dh_shlibdeps) are now only run for arch
931 dependent packages by default (i.e. they are excluded from
932 *-indep targets and are passed -a by default).
933 If you need them for *-indep targets, you can add an
935 explicit Build-Depends on dh-sequence-elf-tools.
936
938 Multiple binary package support
939 If your source package generates more than one binary package,
940 debhelper programs will default to acting on all binary packages when
941 run. If your source package happens to generate one architecture
942 dependent package, and another architecture independent package, this
943 is not the correct behavior, because you need to generate the
944 architecture dependent packages in the binary-arch debian/rules target,
945 and the architecture independent packages in the binary-indep
946 debian/rules target.
947 To facilitate this, as well as give you more control over which
949 packages are acted on by debhelper programs, all debhelper programs
950 accept the -a, -i, -p, and -s parameters. These parameters are
951 cumulative. If none are given, debhelper programs default to acting on
952 all packages listed in the control file, with the exceptions below.
953 First, any package whose Architecture field in debian/control does not
955 match the DEB_HOST_ARCH architecture will be excluded ("Debian Policy,
956 section 5.6.8").
957 Also, some additional packages may be excluded based on the contents of
959 the DEB_BUILD_PROFILES environment variable and Build-Profiles fields
960 in binary package stanzas in debian/control, according to the draft
961 policy at <https://wiki.debian.org/BuildProfileSpec>.
962 Interaction between package selections and Build-Profiles
964 Build-Profiles affect which packages are included in the package
966 selections mechanisms in debhelper. Generally, the package selections
967 are described from the assumption that all packages are enabled. This
968 section describes how the selections react when a package is disabled
969 due to the active Build-Profiles (or lack of active Build-Profiles).
970 -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)
972 The package disabled by Build-Profiles is silently excluded from
973 the selection.
974 Note you will receive a warning if all packages related to these
976 selections are disabled. In that case, it generally does not make
977 sense to do the build in the first place.
978 -N package / --no-package package
980 The option is accepted and effectively does nothing.
981 -p package / --package package
983 The option is accepted, but debhelper will not act on the package.
984 Note that it does not matter whether a package is enabled or disabled
986 by default.
987 Automatic generation of Debian install scripts
989 Some debhelper commands will automatically generate parts of Debian
990 maintainer scripts. If you want these automatically generated things
991 included in your existing Debian maintainer scripts, then you need to
992 add #DEBHELPER# to your scripts, in the place the code should be added.
993 #DEBHELPER# will be replaced by any auto-generated code when you run
994 dh_installdeb.
995 If a script does not exist at all and debhelper needs to add something
997 to it, then debhelper will create the complete script.
998 All debhelper commands that automatically generate code in this way let
1000 it be disabled by the -n parameter (see above).
1001 Note that the inserted code will be shell code, so you cannot directly
1003 use it in a Perl script. If you would like to embed it into a Perl
1004 script, here is one way to do that (note that I made sure that $1, $2,
1005 etc are set with the set command):
1006 my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
1008 #DEBHELPER#
1009 EOF
1010 if (system($temp)) {
1011 my $exit_code = ($? >> 8) & 0xff;
1012 my $signal = $? & 0x7f;
1013 if ($exit_code) {
1014 die("The debhelper script failed with error code: ${exit_code}");
1015 } else {
1016 die("The debhelper script was killed by signal: ${signal}");
1017 }
1018 }
1019 Automatic generation of miscellaneous dependencies.
1021 Some debhelper commands may make the generated package need to depend
1022 on some other packages. For example, if you use dh_installdebconf(1),
1023 your package will generally need to depend on debconf. Or if you use
1024 dh_installxfonts(1), your package will generally need to depend on a
1025 particular version of xutils. Keeping track of these miscellaneous
1026 dependencies can be annoying since they are dependent on how debhelper
1027 does things, so debhelper offers a way to automate it.
1028 All commands of this type, besides documenting what dependencies may be
1030 needed on their man pages, will automatically generate a substvar
1031 called ${misc:Depends}. If you put that token into your debian/control
1032 file, it will be expanded to the dependencies debhelper figures you
1033 need.
1034 This is entirely independent of the standard ${shlibs:Depends}
1036 generated by dh_makeshlibs(1), and the ${perl:Depends} generated by
1037 dh_perl(1). You can choose not to use any of these, if debhelper's
1038 guesses don't match reality.
1039 Package build directories
1041 By default, all debhelper programs assume that the temporary directory
1042 used for assembling the tree of files in a package is debian/package.
1043 Sometimes, you might want to use some other temporary directory. This
1045 is supported by the -P flag. For example, "dh_installdocs
1046 -Pdebian/tmp", will use debian/tmp as the temporary directory. Note
1047 that if you use -P, the debhelper programs can only be acting on a
1048 single package at a time. So if you have a package that builds many
1049 binary packages, you will need to also use the -p flag to specify which
1050 binary package the debhelper program will act on.
1051 udebs
1053 Debhelper includes support for udebs. To create a udeb with debhelper,
1054 add "Package-Type: udeb" to the package's stanza in debian/control.
1055 Debhelper will try to create udebs that comply with debian-installer
1056 policy, by making the generated package files end in .udeb, not
1057 installing any documentation into a udeb, skipping over preinst,
1058 postrm, prerm, and config scripts, etc.
1059
1061 The following environment variables can influence the behavior of
1062 debhelper. It is important to note that these must be actual
1063 environment variables in order to function properly (not simply
1064 Makefile variables). To specify them properly in debian/rules, be sure
1065 to "export" them. For example, "export DH_VERBOSE".
1066 DH_VERBOSE
1068 Set to 1 to enable verbose mode. Debhelper will output every
1069 command it runs. Also enables verbose build logs for some build
1070 systems like autoconf.
1071 DH_QUIET
1073 Set to 1 to enable quiet mode. Debhelper will not output commands
1074 calling the upstream build system nor will dh print which
1075 subcommands are called and depending on the upstream build system
1076 might make that more quiet, too. This makes it easier to spot
1077 important messages but makes the output quite useless as buildd
1078 log. Ignored if DH_VERBOSE is also set.
1079 DH_COMPAT
1081 Temporarily specifies what compatibility level debhelper should run
1082 at, overriding any value specified via Build-Depends on debhelper-
1083 compat or via the debian/compat file.
1084 DH_NO_ACT
1086 Set to 1 to enable no-act mode.
1087 DH_OPTIONS
1089 Anything in this variable will be prepended to the command line
1090 arguments of all debhelper commands.
1091 When using dh(1), it can be passed options that will be passed on
1093 to each debhelper command, which is generally better than using
1094 DH_OPTIONS.
1095 DH_ALWAYS_EXCLUDE
1097 If set, this adds the value the variable is set to to the -X
1098 options of all commands that support the -X option. Moreover,
1099 dh_builddeb will rm -rf anything that matches the value in your
1100 package build tree.
1101 This can be useful if you are doing a build from a CVS source tree,
1103 in which case setting DH_ALWAYS_EXCLUDE=CVS will prevent any CVS
1104 directories from sneaking into the package you build. Or, if a
1105 package has a source tarball that (unwisely) includes CVS
1106 directories, you might want to export DH_ALWAYS_EXCLUDE=CVS in
1107 debian/rules, to make it take effect wherever your package is
1108 built.
1109 Multiple things to exclude can be separated with colons, as in
1111 DH_ALWAYS_EXCLUDE=CVS:.svn
1112 DH_EXTRA_ADDONS
1114 If set, this adds the specified dh addons to be run in the
1115 appropriate places in the sequence of commands. This is equivalent
1116 to specifying the addon to run with the --with flag in the
1117 debian/rules file. Any --without calls specifying an addon in this
1118 environment variable will not be run.
1119 This is intended to be used by downstreams or specific local
1121 configurations that require a debhelper addon to be run during
1122 multiple builds without having to patch a large number of rules
1123 file. If at all possible, this should be avoided in favor of a
1124 --with flag in the rules file.
1125 CFLAGS, CPPFLAGS, CXXFLAGS, OBJCFLAGS, OBJCXXFLAGS, GCJFLAGS, FFLAGS,
1127 FCFLAGS, LDFLAGS
1128 By default (in any non-deprecated compat level), debhelper will
1129 automatically set these flags by using dpkg-buildflags(1), when
1130 they are unset. If you need to change the default flags, please
1131 use the features from dpkg-buildflags(1) to do this (e.g.
1132 DEB_BUILD_MAINT_OPTIONS=hardening=all or
1133 DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true) rather than setting
1134 the concrete variable directly.
1135
1137 /usr/share/doc/debhelper/examples/
1138 A set of example debian/rules files that use debhelper.
1139 <http://joeyh.name/code/debhelper/>
1141 Debhelper web site.
1142
1144 Joey Hess <joeyh@debian.org>
114512.6.1 2019-10-08 debhelper(7)