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 --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 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 export DEB_CFLAGS_MAINT_APPEND=-O3
452 %:
454 dh $@
455 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 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 This option is only available with debhelper (>= 12.7~) when the
467 package uses compatibility level 9 or later.
468 --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
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 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 Build-Depends: debhelper-compat (= 12)
489 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 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 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 Build-Depends: debhelper (>= 12~)
512 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 Supported compatibility levels
521 These are the available compatibility levels:
522 v5 This is the lowest supported compatibility level.
524 If you are upgrading from an earlier compatibility level, please
526 review debhelper-obsolete-compat(7).
527 This mode is deprecated.
529 v6 Changes from v5 are:
531 - Commands that generate maintainer script fragments will
533 order the fragments in reverse order for the prerm and
534 postrm scripts.
535 - 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 - 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 - 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 This mode is deprecated.
549 v7 Changes from v6 are:
551 - 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 - dh_clean will read debian/clean and delete files listed
560 there.
561 - dh_clean will delete toplevel *-stamp files.
563 - dh_installchangelogs will guess at what file is the
565 upstream changelog if none is specified.
566 This mode is deprecated.
568 v8 Changes from v7 are:
570 - Commands will fail rather than warning when they are passed
572 unknown options.
573 - 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 - 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 - dh_auto_* prefer to use Perl's Module::Build in preference
586 to Makefile.PL.
587 This mode is deprecated.
589 v9 Changes from v8 are:
591 - Multiarch support. In particular, dh_auto_configure passes
593 multiarch directories to autoconf in --libdir and
594 --libexecdir.
595 - 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 - dh_strip compresses debugging symbol files to reduce the
603 installed size of -dbg packages.
604 - dh_auto_configure does not include the source package name
606 in --libexecdir when using autoconf.
607 - dh does not default to enabling --with=python-support
609 (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 - All of the dh_auto_* debhelper programs and dh set
615 environment variables listed by dpkg-buildflags, unless
616 they are already set.
617 - dh_auto_configure passes dpkg-buildflags CFLAGS, CPPFLAGS,
619 and LDFLAGS to perl Makefile.PL and Build.PL
620 - dh_strip puts separated debug symbols in a location based
622 on their build-id.
623 - Executable debhelper config files are run and their output
625 used as the configuration.
626 v10 Changes from v9 are:
628 - dh_installinit will no longer install a file named
630 debian/package as an init script.
631 - 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 - dh_installdeb no longer installs a maintainer-provided
637 debian/package.shlibs file. This is now done by
638 dh_makeshlibs instead.
639 - 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 - 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 - 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 Retroactively applied to earlier compat levels: dh no
654 longer accepts any of these since debhelper/12.4.
655 - 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 The main effects of this are:
662 - 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 - 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 Example of where it can go wrong:
674 override_dh_foo:
676 dh_foo -pmy-pkg
677 override_dh_bar:
679 dh_bar
680 dh_foo --remaining
681 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 - 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 - 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 - 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 - 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 - 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 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 v11 This mode is discouraged.
718 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 Changes from v10 are:
727 - 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 - 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 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 - dh_installdirs no longer creates debian/package directories
743 unless explicitly requested (or it has to create a
744 subdirectory in it).
745 The vast majority of all packages will be unaffected by
747 this change.
748 - 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 - The autoconf buildsystem now passes --runstatedir=/run to
754 ./configure.
755 - The cmake buildsystem now passes
757 -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
758 - dh_installman will now prefer detecting the language from
760 the path name rather than the extension.
761 - 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 - 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 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 - 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 Migration note: A bug in debhelper 11 up to 11.1.5 made
784 dh_installinfo incorrectly ignore --sourcedir.
785 - 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 - 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 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 - 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 - 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 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 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 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 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 - 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 This change may cause the tools to process more files than
841 previously.
842 v12 This is the recommended mode of operation.
844 Changes from v11 are:
846 - 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 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 - The -s (--same-arch) option is removed. Please use -a
857 (--arch) instead.
858 - Invoking dh_clean -k now causes an error instead of a
860 deprecation warning.
861 - The --no-restart-on-upgrade option in dh_installinit has
863 been removed. Please use the new name --no-stop-on-upgrade
864 - 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 - 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 - 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 - 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 - The dh_missing tool will now default to --list-missing.
888 - 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 - The dh_compress tool no longer compresses examples (i.e.
894 anything installed in </usr/share/doc/package/examples>.)
895 - 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 - 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 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 override_dh_auto_configure:
913 dh_auto_configure -- --libexecdir=/usr/libexec
914 Note the -- before the --libexecdir parameter.
916 - 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 - 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 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 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 - 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 - dh_installsystemduser is now included in the dh standard
946 sequence by default.
947 - The python-distutils buildsystem is now removed. Please
949 use the third-party build system pybuild instead.
950 v13 This compatibility level is still open for development; use with
952 caution.
953 Changes from v12 are:
955 - 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 - 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 - 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 If you need them for *-indep targets, you can add an
974 explicit Build-Depends on dh-sequence-elf-tools.
975 - 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 - 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 - 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
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 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 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 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 Interaction between package selections and Build-Profiles
1021 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 -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 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 -N package / --no-package package
1037 The option is accepted and effectively does nothing.
1038 -p package / --package package
1040 The option is accepted, but debhelper will not act on the package.
1041 Note that it does not matter whether a package is enabled or disabled
1043 by default.
1044 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 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 All debhelper commands that automatically generate code in this way let
1057 it be disabled by the -n parameter (see above).
1058 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 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 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 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 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 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 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 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
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 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 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 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 DH_NO_ACT
1143 Set to 1 to enable no-act mode.
1144 DH_OPTIONS
1146 Anything in this variable will be prepended to the command line
1147 arguments of all debhelper commands.
1148 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 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 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 Multiple things to exclude can be separated with colons, as in
1168 DH_ALWAYS_EXCLUDE=CVS:.svn
1169 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 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 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 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 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
1204 /usr/share/doc/debhelper/examples/
1205 A set of example debian/rules files that use debhelper.
1206 <http://joeyh.name/code/debhelper/>
1208 Debhelper web site.
1209
1211 Joey Hess <joeyh@debian.org>
121212.7.3 2020-01-28 debhelper(7)