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 debian/control and
35 debian/compat 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_gconf(1)
76 install GConf defaults files and register schemas
77 dh_gencontrol(1)
79 generate and install control file
80 dh_icons(1)
82 Update caches of Freedesktop icons
83 dh_install(1)
85 install files into package build directories
86 dh_installcatalogs(1)
88 install and register SGML Catalogs
89 dh_installchangelogs(1)
91 install changelogs into package build directories
92 dh_installcron(1)
94 install cron scripts into etc/cron.*
95 dh_installdeb(1)
97 install files into the DEBIAN directory
98 dh_installdebconf(1)
100 install files used by debconf in package build directories
101 dh_installdirs(1)
103 create subdirectories in package build directories
104 dh_installdocs(1)
106 install documentation into package build directories
107 dh_installemacsen(1)
109 register an Emacs add on package
110 dh_installexamples(1)
112 install example files into package build directories
113 dh_installgsettings(1)
115 install GSettings overrides and set dependencies
116 dh_installifupdown(1)
118 install if-up and if-down hooks
119 dh_installinfo(1)
121 install info files
122 dh_installinit(1)
124 install service init files into package build directories
125 dh_installinitramfs(1)
127 install initramfs hooks and setup maintscripts
128 dh_installlogcheck(1)
130 install logcheck rulefiles into etc/logcheck/
131 dh_installlogrotate(1)
133 install logrotate config files
134 dh_installman(1)
136 install man pages into package build directories
137 dh_installmenu(1)
139 install Debian menu files into package build directories
140 dh_installmime(1)
142 install mime files into package build directories
143 dh_installmodules(1)
145 register kernel modules
146 dh_installpam(1)
148 install pam support files
149 dh_installppp(1)
151 install ppp ip-up and ip-down files
152 dh_installsystemd(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_installmanpages(1)
224 old-style man page installer (deprecated)
225 Other Commands
227 If a program's name starts with dh_, and the program is not on the
228 above lists, then it is not part of the debhelper package, but it
229 should still work like the other programs described on this page.
230
232 Many debhelper commands make use of files in debian/ to control what
233 they do. Besides the common debian/changelog and debian/control, which
234 are in all packages, not just those using debhelper, some additional
235 files can be used to configure the behavior of specific debhelper
236 commands. These files are typically named debian/package.foo (where
237 package of course, is replaced with the package that is being acted
238 on).
239 For example, dh_installdocs uses files named debian/package.docs to
241 list the documentation files it will install. See the man pages of
242 individual commands for details about the names and formats of the
243 files they use. Generally, these files will list files to act on, one
244 file per line. Some programs in debhelper use pairs of files and
245 destinations or slightly more complicated formats.
246 Note for the first (or only) binary package listed in debian/control,
248 debhelper will use debian/foo when there's no debian/package.foo file.
249 However, it is often a good idea to keep the package. prefix as it is
250 more explicit. The primary exception to this are files that debhelper
251 by default installs in every binary package when it does not have a
252 package prefix (such as debian/copyright or debian/changelog).
253 In some rare cases, you may want to have different versions of these
255 files for different architectures or OSes. If files named
256 debian/package.foo.ARCH or debian/package.foo.OS exist, where ARCH and
257 OS are the same as the output of "dpkg-architecture -qDEB_HOST_ARCH" /
258 "dpkg-architecture -qDEB_HOST_ARCH_OS", then they will be used in
259 preference to other, more general files.
260 Mostly, these config files are used to specify lists of various types
262 of files. Documentation or example files to install, files to move, and
263 so on. When appropriate, in cases like these, you can use standard
264 shell wildcard characters (? and * and [..] character classes) in the
265 files. You can also put comments in these files; lines beginning with
266 # are ignored.
267 The syntax of these files is intentionally kept very simple to make
269 them easy to read, understand, and modify.
270 Executable debhelper config files
272 If you need additional flexibility, many of the debhelper tools (e.g.
273 dh_install(1)) support executing a config file as a script.
274 To use this feature, simply mark the config file as executable (e.g.
276 chmod +x debian/package.install) and the tool will attempt to execute
277 it and use the output of the script. In many cases, you can use
278 dh-exec(1) as interpreter of the config file to retain most of the
279 original syntax while getting the additional flexibility you need.
280 When using executable debhelper config files, please be aware of the
282 following:
283 · The executable config file must exit with success (i.e. its return
285 code should indicate success).
286 · The output will be used exactly as it is. Notably, debhelper will
288 not expand wildcards or strip comments in the output.
289 If you need the package to build on a file system where you cannot
291 disable the executable bit, then you can use dh-exec(1) and its strip-
292 output script.
293
295 The following command line options are supported by all debhelper
296 programs.
297 -v, --verbose
299 Verbose mode: show all commands that modify the package build
300 directory.
301 --no-act
303 Do not really do anything. If used with -v, the result is that the
304 command will output what it would have done.
305 -a, --arch
307 Act on architecture dependent packages that should be built for the
308 DEB_HOST_ARCH architecture.
309 -i, --indep
311 Act on all architecture independent packages.
312 -ppackage, --package=package
314 Act on the package named package. This option may be specified
315 multiple times to make debhelper operate on a given set of
316 packages.
317 -s, --same-arch
319 Deprecated alias of -a.
320 This option is removed in compat 12.
322 -Npackage, --no-package=package
324 Do not act on the specified package even if an -a, -i, or -p option
325 lists the package as one that should be acted on.
326 --remaining-packages
328 Do not act on the packages which have already been acted on by this
329 debhelper command earlier (i.e. if the command is present in the
330 package debhelper log). For example, if you need to call the
331 command with special options only for a couple of binary packages,
332 pass this option to the last call of the command to process the
333 rest of packages with default settings.
334 --ignore=file
336 Ignore the specified file. This can be used if debian/ contains a
337 debhelper config file that a debhelper command should not act on.
338 Note that debian/compat, debian/control, and debian/changelog can't
339 be ignored, but then, there should never be a reason to ignore
340 those files.
341 For example, if upstream ships a debian/init that you don't want
343 dh_installinit to install, use --ignore=debian/init
344 -Ptmpdir, --tmpdir=tmpdir
346 Use tmpdir for package build directory. The default is
347 debian/package
348 --mainpackage=package
350 This little-used option changes the package which debhelper
351 considers the "main package", that is, the first one listed in
352 debian/control, and the one for which debian/foo files can be used
353 instead of the usual debian/package.foo files.
354 -O=option|bundle
356 This is used by dh(1) when passing user-specified options to all
357 the commands it runs. If the command supports the specified option
358 or option bundle, it will take effect. If the command does not
359 support the option (or any part of an option bundle), it will be
360 ignored.
361
363 The following command line options are supported by some debhelper
364 programs. See the man page of each program for a complete explanation
365 of what each option does.
366 -n Do not modify postinst, postrm, etc. scripts.
368 -Xitem, --exclude=item
370 Exclude an item from processing. This option may be used multiple
371 times, to exclude more than one thing. The item is typically part
372 of a filename, and any file containing the specified text will be
373 excluded.
374 -A, --all
376 Makes files or other items that are specified on the command line
377 take effect in ALL packages acted on, not just the first.
378
380 The following command line options are supported by all of the
381 dh_auto_* debhelper programs. These programs support a variety of build
382 systems, and normally heuristically determine which to use, and how to
383 use them. You can use these command line options to override the
384 default behavior. Typically these are passed to dh(1), which then
385 passes them to all the dh_auto_* programs.
386 -Sbuildsystem, --buildsystem=buildsystem
388 Force use of the specified buildsystem, instead of trying to auto-
389 select one which might be applicable for the package.
390 -Ddirectory, --sourcedirectory=directory
392 Assume that the original package source tree is at the specified
393 directory rather than the top level directory of the Debian source
394 package tree.
395 -B[directory], --builddirectory=[directory]
397 Enable out of source building and use the specified directory as
398 the build directory. If directory parameter is omitted, a default
399 build directory will be chosen.
400 If this option is not specified, building will be done in source by
402 default unless the build system requires or prefers out of source
403 tree building. In such a case, the default build directory will be
404 used even if --builddirectory is not specified.
405 If the build system prefers out of source tree building but still
407 allows in source building, the latter can be re-enabled by passing
408 a build directory path that is the same as the source directory
409 path.
410 --parallel, --no-parallel
412 Control whether parallel builds should be used if underlying build
413 system supports them. The number of parallel jobs is controlled by
414 the DEB_BUILD_OPTIONS environment variable ("Debian Policy, section
415 4.9.1") at build time. It might also be subject to a build system
416 specific limit.
417 If neither option is specified, debhelper currently defaults to
419 --parallel in compat 10 (or later) and --no-parallel otherwise.
420 As an optimization, dh will try to avoid passing these options to
422 subprocesses, if they are unnecessary and the only options passed.
423 Notably this happens when DEB_BUILD_OPTIONS does not have a
424 parallel parameter (or its value is 1).
425 --max-parallel=maximum
427 This option implies --parallel and allows further limiting the
428 number of jobs that can be used in a parallel build. If the package
429 build is known to only work with certain levels of concurrency, you
430 can set this to the maximum level that is known to work, or that
431 you wish to support.
432 Notably, setting the maximum to 1 is effectively the same as using
434 --no-parallel.
435 --list, -l
437 List all build systems supported by debhelper on this system. The
438 list includes both default and third party build systems (marked as
439 such). Also shows which build system would be automatically
440 selected, or which one is manually specified with the --buildsystem
441 option.
442
444 From time to time, major non-backwards-compatible changes need to be
445 made to debhelper, to keep it clean and well-designed as needs change
446 and its author gains more experience. To prevent such major changes
447 from breaking existing packages, the concept of debhelper compatibility
448 levels was introduced. You must tell debhelper which compatibility
449 level it should use, and it modifies its behavior in various ways. The
450 compatibility level is specified in the debian/compat file and the file
451 must be present.
452 Tell debhelper what compatibility level to use by writing a number to
454 debian/compat. For example, to use v11 mode:
455 % echo 11 > debian/compat
457 Your package will also need a versioned build dependency on a version
459 of debhelper equal to (or greater than) the compatibility level your
460 package uses. So for compatibility level 11, ensure debian/control has:
461 Build-Depends: debhelper (>= 11~)
463 Unless otherwise indicated, all debhelper documentation assumes that
465 you are using the most recent compatibility level, and in most cases
466 does not indicate if the behavior is different in an earlier
467 compatibility level, so if you are not using the most recent
468 compatibility level, you're advised to read below for notes about what
469 is different in earlier compatibility levels.
470 Supported compatibility levels
472 These are the available compatibility levels:
473 v5 This is the lowest supported compatibility level.
475 If you are upgrading from an earlier compatibility level, please
477 review debhelper-obsolete-compat(7).
478 This mode is deprecated.
480 v6 Changes from v5 are:
482 - Commands that generate maintainer script fragments will
484 order the fragments in reverse order for the prerm and
485 postrm scripts.
486 - dh_installwm will install a slave manpage link for
488 x-window-manager.1.gz, if it sees the man page in
489 usr/share/man/man1 in the package build directory.
490 - dh_builddeb did not previously delete everything matching
492 DH_ALWAYS_EXCLUDE, if it was set to a list of things to
493 exclude, such as CVS:.svn:.git. Now it does.
494 - dh_installman allows overwriting existing man pages in the
496 package build directory. In previous compatibility levels
497 it silently refuses to do this.
498 This mode is deprecated.
500 v7 Changes from v6 are:
502 - dh_install, will fall back to looking for files in
504 debian/tmp if it doesn't find them in the current directory
505 (or wherever you tell it look using --sourcedir). This
506 allows dh_install to interoperate with dh_auto_install,
507 which installs to debian/tmp, without needing any special
508 parameters.
509 - dh_clean will read debian/clean and delete files listed
511 there.
512 - dh_clean will delete toplevel *-stamp files.
514 - dh_installchangelogs will guess at what file is the
516 upstream changelog if none is specified.
517 This mode is deprecated.
519 v8 Changes from v7 are:
521 - Commands will fail rather than warning when they are passed
523 unknown options.
524 - dh_makeshlibs will run dpkg-gensymbols on all shared
526 libraries that it generates shlibs files for. So -X can be
527 used to exclude libraries. Also, libraries in unusual
528 locations that dpkg-gensymbols would not have processed
529 before will be passed to it, a behavior change that can
530 cause some packages to fail to build.
531 - dh requires the sequence to run be specified as the first
533 parameter, and any switches come after it. Ie, use "dh $@
534 --foo", not "dh --foo $@".
535 - dh_auto_* prefer to use Perl's Module::Build in preference
537 to Makefile.PL.
538 This mode is deprecated.
540 v9 Changes from v8 are:
542 - Multiarch support. In particular, dh_auto_configure passes
544 multiarch directories to autoconf in --libdir and
545 --libexecdir.
546 - dh is aware of the usual dependencies between targets in
548 debian/rules. So, "dh binary" will run any build, build-
549 arch, build-indep, install, etc targets that exist in the
550 rules file. There's no need to define an explicit binary
551 target with explicit dependencies on the other targets.
552 - dh_strip compresses debugging symbol files to reduce the
554 installed size of -dbg packages.
555 - dh_auto_configure does not include the source package name
557 in --libexecdir when using autoconf.
558 - dh does not default to enabling --with=python-support
560 (Obsolete: As the dh_pysupport tool was removed from Debian
562 stretch. Since debhelper/10.3, dh no longer enables this
563 sequence add-on regardless of compat level)
564 - All of the dh_auto_* debhelper programs and dh set
566 environment variables listed by dpkg-buildflags, unless
567 they are already set.
568 - dh_auto_configure passes dpkg-buildflags CFLAGS, CPPFLAGS,
570 and LDFLAGS to perl Makefile.PL and Build.PL
571 - dh_strip puts separated debug symbols in a location based
573 on their build-id.
574 - Executable debhelper config files are run and their output
576 used as the configuration.
577 v10 Changes from v9 are:
579 - dh_installinit will no longer install a file named
581 debian/package as an init script.
582 - dh_installdocs will error out if it detects links created
584 with --link-doc between packages of architecture "all" and
585 non-"all" as it breaks binNMUs.
586 - dh_installdeb no longer installs a maintainer-provided
588 debian/package.shlibs file. This is now done by
589 dh_makeshlibs instead.
590 - dh_installwm refuses to create a broken package if no man
592 page can be found (required to register for the x-window-
593 manager alternative).
594 - Debhelper will default to --parallel for all buildsystems
596 that support parallel building. This can be disabled by
597 using either --no-parallel or passing --max-parallel with a
598 value of 1.
599 - The dh command will not accept any of the deprecated
601 "manual sequence control" parameters (--before, --after,
602 etc.). Please use override targets instead.
603 - The dh command will no longer use log files to track which
605 commands have been run. The dh command still keeps track
606 of whether it already ran the "build" sequence and skip it
607 if it did.
608 The main effects of this are:
610 - With this, it is now easier to debug the install or/and
612 binary sequences because they can now trivially be re-
613 run (without having to do a full "clean and rebuild"
614 cycle)
615 - The main caveat is that dh_* now only keeps track of
617 what happened in a single override target. When all
618 the calls to a given dh_cmd command happens in the same
619 override target everything will work as before.
620 Example of where it can go wrong:
622 override_dh_foo:
624 dh_foo -pmy-pkg
625 override_dh_bar:
627 dh_bar
628 dh_foo --remaining
629 In this case, the call to dh_foo --remaining will also
631 include my-pkg, since dh_foo -pmy-pkg was run in a
632 separate override target. This issue is not limited to
633 --remaining, but also includes -a, -i, etc.
634 - The dh_installdeb command now shell-escapes the lines in
636 the maintscript config file. This was the original intent
637 but it did not work properly and packages have begun to
638 rely on the incomplete shell escaping (e.g. quoting file
639 names).
640 - The dh_installinit command now defaults to
642 --restart-after-upgrade. For packages needing the previous
643 behaviour, please use --no-restart-after-upgrade.
644 - The autoreconf sequence is now enabled by default. Please
646 pass --without autoreconf to dh if this is not desirable
647 for a given package
648 - The systemd sequence is now enabled by default. Please
650 pass --without systemd to dh if this is not desirable for a
651 given package.
652 - Retroactively removed: dh no longer creates the package
654 build directory when skipping running debhelper commands.
655 This will not affect packages that only build with
656 debhelper commands, but it may expose bugs in commands not
657 included in debhelper.
658 This compatibility feature had a bug since its inception in
660 debhelper/9.20130516 that made it fail to apply in compat 9
661 and earlier. As there has been no reports of issues caused
662 by this bug in those ~5 years, this item have been removed
663 rather than fixed.
664 v11 This is the recommended mode of operation.
666 Changes from v10 are:
668 - dh_installinit no longer installs service or tmpfile files,
670 nor generates maintainer scripts for those files. Please
671 use the new dh_installsystemd helper.
672 - The dh_systemd_enable and dh_systemd_start helpers have
674 been replaced by the new dh_installsystemd helper. For the
675 same reason, the systemd sequence for dh has also been
676 removed. If you need to disable the dh_installsystemd
677 helper tool, please use an empty override target.
678 Please note that the dh_installsystemd tool has a slightly
680 different behaviour in some cases (e.g. when using the
681 --name parameter).
682 - dh_installdirs no longer creates debian/package directories
684 unless explicitly requested (or it has to create a
685 subdirectory in it).
686 The vast majority of all packages will be unaffected by
688 this change.
689 - The makefile buildsystem now passes INSTALL=install
691 --strip-program=true to make(1). Derivative buildsystems
692 (e.g. configure or cmake) are unaffected by this change.
693 - The autoconf buildsystem now passes --runstatedir=/run to
695 ./configure.
696 - The cmake buildsystem now passes
698 -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
699 - dh_installman will now prefer detecting the language from
701 the path name rather than the extension.
702 - dh_auto_install will now only create the destination
704 directory it needs. Previously, it would create the
705 package build directory for all packages. This will not
706 affect packages that only build with debhelper commands,
707 but it may expose bugs in commands not included in
708 debhelper.
709 - The helpers dh_installdocs, dh_installexamples,
711 dh_installinfo, and dh_installman now error out if their
712 config has a pattern that does not match anything or
713 reference a path that does not exist.
714 Known exceptions include building with the nodoc profile,
716 where the above tools will silently permit failed matches
717 where the patterns are used to specify documentation.
718 - The helpers dh_installdocs, dh_installexamples,
720 dh_installinfo, and dh_installman now accept the parameter
721 --sourcedir with same meaning as dh_install. Furthermore,
722 they now also fall back to debian/tmp like dh_install.
723 Migration note: A bug in debhelper 11 up to 11.1.5 made
725 dh_installinfo incorrectly ignore --sourcedir.
726 - The perl-makemaker and perl-build build systems no longer
728 pass -I. to perl. Packages that still need this behaviour
729 can emulate it by using the PERL5LIB environment variable.
730 E.g. by adding export PERL5LIB=. in their debian/rules file
731 (or similar).
732 - The PERL_USE_UNSAFE_INC environment variable is no longer
734 set by dh or any of the dh_auto_* tools. It was added as a
735 temporary work around to avoid a lot of packages failing to
736 build at the same time.
737 Note this item will eventually become obsolete as upstream
739 intends to drop support for the PERL_USE_UNSAFE_INC
740 environment variable. When perl drops support for it, then
741 this variable will be removed retroactively from existing
742 compat levels as well.
743 - The dh_makeshlibs helper will now exit with an error if
745 objdump returns a non-zero exit from analysing a given
746 file.
747 - The dh_installdocs and dh_installexamples tools may now
749 install most of the documentation in a different path to
750 comply with the recommendation from Debian policy §12.3
751 (since version 3.9.7).
752 Note that if a given source package only contains a single
754 binary package in debian/control or none of the packages
755 are -doc packages, then this change is not relevant for
756 that source package and you can skip to the next change.
757 By default, these tools will now attempt to determine a
759 "main package for the documentation" (called a doc-main-
760 package from here on) for every -doc package. If they find
761 such a doc-main-package, they will now install the
762 documentation into the path /usr/share/doc/doc-main-package
763 in the given doc package. I.e. the path can change but the
764 documentation is still shipped in the -doc package.
765 The --doc-main-package option can be used when the auto-
767 detection is insufficient or to reset the path to its
768 previous value if there is a reason to diverge from Debian
769 policy recommendation.
770 Some documentation will not be affected by this change.
772 These exceptions include the copyright file, changelog
773 files, README.Debian, etc. These files will still be
774 installed in the path /usr/share/doc/package.
775 - The dh_strip and dh_shlibdeps tools no longer uses filename
777 patterns to determine which files to process. Instead,
778 they open the file and look for an ELF header to determine
779 if a given file is an shared object or an ELF executable.
780 This change may cause the tools to process more files than
782 previously.
783 v12 This compatibility level is open for beta testing; changes may
785 occur.
786 Changes from v11 are:
788 - The dh_makeshlibs tool now generates shlibs files with
790 versioned dependency by default. This means that
791 -VUpstream-Version (a.k.a. -V) is now the default.
792 If an unversioned dependency in the shlibs file is wanted,
794 this can be obtained by passing -VNone instead. However,
795 please see dh_makeshlibs(1) for the caveat of unversioned
796 dependencies.
797 - The -s (--same-arch) option is removed. Please use -a
799 (--arch) instead.
800 - Invoking dh_clean -k now causes an error instead of a
802 deprecation warning.
803 - The --no-restart-on-upgrade option in dh_installinit has
805 been removed. Please use the new name --no-stop-on-upgrade
806 - There was a bug in the doit (and similar) functions from
808 Debian::Debhelper::Dh_Lib that made them spawn a shell in
809 one particular circumstance. This bug is now removed and
810 will cause helpers that rely on the bug to fail with a
811 "command not found"-error.
812 - The --list-missing and --fail-missing in dh_install has
814 been removed. Please use dh_missing and its corresponding
815 options, which can also see the files installed by other
816 helpers.
817 - The dh_installinit helper no longer installs configuration
819 for the upstart init system. Instead, it will abort the
820 build if it finds an old upstart configuration file. The
821 error is there to remind the package maintainer to ensure
822 the proper removal of the conffiles shipped in previous
823 versions of the package (if any).
824 - The dh_installdeb tool will do basic validation of some
826 dpkg-maintscript-helper(1) commands and will error out if
827 the commands appear to be invalid.
828 - The dh_missing tool will now default to --list-missing.
830 - The dh_makeshlibs tool will now only pass libraries to
832 dpkg-gensymbols(1) if the ELF binary has a SONAME
833 (containing ".so").
834 - The dh_compress tool no longer compresses examples (i.e.
836 anything installed in </usr/share/doc/package/examples>.)
837 - The standard sequence in dh now includes dh_dwz and
839 dh_installinitramfs by default. This makes the dwz and
840 installinitramfs sequences obsolete and they will now fail
841 with an error. If you want to skip these commands, then
842 please insert an empty override target for them in
843 debian/rules (e.g. override_dh_dwz:)
844 - The build systems meson and autoconf no longer explicitly
846 set the --libexecdir variable and thus relies on the build
847 system default - which should be /usr/libexec (per FHS 3.0,
848 adopted in Debian Policy 4.1.5).
849 If a particular upstream package does not use the correct
851 default, the parameter can often be passed manually via
852 dh_auto_configure(1). E.g. via the following example:
853 override_dh_auto_configure:
855 dh_auto_configure -- --libexecdir=/usr/libexec
856 Note the -- before the --libexecdir parameter.
858 - The dh_installdeb tool no longer installs the maintainer
860 provided conffiles file. The file has mostly been obsolete
861 since compatibility level 3, where dh_installdeb began to
862 automatically compute the resulting conffiles control file.
863 - The dh_installsystemd tool no longer relies on
865 dh_installinit for handling systemd services that have a
866 sysvinit alternative. Both tools must now be used in such
867 a case to ensure the service is properly started under both
868 sysvinit and systemd.
869 If you have an override for dh_installinit (e.g. to call it
871 with --no-start) then you will probably need one for
872 dh_installsystemd as well now.
873 This change makes dh_installinit inject a misc:Pre-Depends
875 for init-system-helpers (>= 1.54~). Please ensure that the
876 package lists ${misc:Pre-Depends} in its Pre-Depends field
877 before upgrading to compat 12.
878 - The third-party dh_golang tool (from dh-golang package) now
880 defaults on honoring DH_GOLANG_EXCLUDES variable for source
881 installation in -dev packages and not only during the
882 building process. Please set DH_GOLANG_EXCLUDES_ALL to
883 false to revert to the previous behaviour. See
884 Debian::Debhelper::Buildsystem::golang(3pm) for details and
885 examples.
886
888 Multiple binary package support
889 If your source package generates more than one binary package,
890 debhelper programs will default to acting on all binary packages when
891 run. If your source package happens to generate one architecture
892 dependent package, and another architecture independent package, this
893 is not the correct behavior, because you need to generate the
894 architecture dependent packages in the binary-arch debian/rules target,
895 and the architecture independent packages in the binary-indep
896 debian/rules target.
897 To facilitate this, as well as give you more control over which
899 packages are acted on by debhelper programs, all debhelper programs
900 accept the -a, -i, -p, and -s parameters. These parameters are
901 cumulative. If none are given, debhelper programs default to acting on
902 all packages listed in the control file, with the exceptions below.
903 First, any package whose Architecture field in debian/control does not
905 match the DEB_HOST_ARCH architecture will be excluded ("Debian Policy,
906 section 5.6.8").
907 Also, some additional packages may be excluded based on the contents of
909 the DEB_BUILD_PROFILES environment variable and Build-Profiles fields
910 in binary package stanzas in debian/control, according to the draft
911 policy at <https://wiki.debian.org/BuildProfileSpec>.
912 Interaction between package selections and Build-Profiles
914 Build-Profiles affect which packages are included in the package
916 selections mechanisms in debhelper. Generally, the package selections
917 are described from the assumption that all packages are enabled. This
918 section describes how the selections react when a package is disabled
919 due to the active Build-Profiles (or lack of active Build-Profiles).
920 -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)
922 The package disabled by Build-Profiles is silently excluded from
923 the selection.
924 Note you will receive a warning if all packages related to these
926 selections are disabled. In that case, it generally does not make
927 sense to do the build in the first place.
928 -N package / --no-package package
930 The option is accepted and effectively does nothing.
931 -p package / --package package
933 The option is accepted, but debhelper will not act on the package.
934 Note that it does not matter whether a package is enabled or disabled
936 by default.
937 Automatic generation of Debian install scripts
939 Some debhelper commands will automatically generate parts of Debian
940 maintainer scripts. If you want these automatically generated things
941 included in your existing Debian maintainer scripts, then you need to
942 add #DEBHELPER# to your scripts, in the place the code should be added.
943 #DEBHELPER# will be replaced by any auto-generated code when you run
944 dh_installdeb.
945 If a script does not exist at all and debhelper needs to add something
947 to it, then debhelper will create the complete script.
948 All debhelper commands that automatically generate code in this way let
950 it be disabled by the -n parameter (see above).
951 Note that the inserted code will be shell code, so you cannot directly
953 use it in a Perl script. If you would like to embed it into a Perl
954 script, here is one way to do that (note that I made sure that $1, $2,
955 etc are set with the set command):
956 my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
958 #DEBHELPER#
959 EOF
960 if (system($temp)) {
961 my $exit_code = ($? >> 8) & 0xff;
962 my $signal = $? & 0x7f;
963 if ($exit_code) {
964 die("The debhelper script failed with error code: ${exit_code}");
965 } else {
966 die("The debhelper script was killed by signal: ${signal}");
967 }
968 }
969 Automatic generation of miscellaneous dependencies.
971 Some debhelper commands may make the generated package need to depend
972 on some other packages. For example, if you use dh_installdebconf(1),
973 your package will generally need to depend on debconf. Or if you use
974 dh_installxfonts(1), your package will generally need to depend on a
975 particular version of xutils. Keeping track of these miscellaneous
976 dependencies can be annoying since they are dependent on how debhelper
977 does things, so debhelper offers a way to automate it.
978 All commands of this type, besides documenting what dependencies may be
980 needed on their man pages, will automatically generate a substvar
981 called ${misc:Depends}. If you put that token into your debian/control
982 file, it will be expanded to the dependencies debhelper figures you
983 need.
984 This is entirely independent of the standard ${shlibs:Depends}
986 generated by dh_makeshlibs(1), and the ${perl:Depends} generated by
987 dh_perl(1). You can choose not to use any of these, if debhelper's
988 guesses don't match reality.
989 Package build directories
991 By default, all debhelper programs assume that the temporary directory
992 used for assembling the tree of files in a package is debian/package.
993 Sometimes, you might want to use some other temporary directory. This
995 is supported by the -P flag. For example, "dh_installdocs
996 -Pdebian/tmp", will use debian/tmp as the temporary directory. Note
997 that if you use -P, the debhelper programs can only be acting on a
998 single package at a time. So if you have a package that builds many
999 binary packages, you will need to also use the -p flag to specify which
1000 binary package the debhelper program will act on.
1001 udebs
1003 Debhelper includes support for udebs. To create a udeb with debhelper,
1004 add "Package-Type: udeb" to the package's stanza in debian/control.
1005 Debhelper will try to create udebs that comply with debian-installer
1006 policy, by making the generated package files end in .udeb, not
1007 installing any documentation into a udeb, skipping over preinst,
1008 postrm, prerm, and config scripts, etc.
1009
1011 The following environment variables can influence the behavior of
1012 debhelper. It is important to note that these must be actual
1013 environment variables in order to function properly (not simply
1014 Makefile variables). To specify them properly in debian/rules, be sure
1015 to "export" them. For example, "export DH_VERBOSE".
1016 DH_VERBOSE
1018 Set to 1 to enable verbose mode. Debhelper will output every
1019 command it runs. Also enables verbose build logs for some build
1020 systems like autoconf.
1021 DH_QUIET
1023 Set to 1 to enable quiet mode. Debhelper will not output commands
1024 calling the upstream build system nor will dh print which
1025 subcommands are called and depending on the upstream build system
1026 might make that more quiet, too. This makes it easier to spot
1027 important messages but makes the output quite useless as buildd
1028 log. Ignored if DH_VERBOSE is also set.
1029 DH_COMPAT
1031 Temporarily specifies what compatibility level debhelper should run
1032 at, overriding any value in debian/compat.
1033 DH_NO_ACT
1035 Set to 1 to enable no-act mode.
1036 DH_OPTIONS
1038 Anything in this variable will be prepended to the command line
1039 arguments of all debhelper commands.
1040 When using dh(1), it can be passed options that will be passed on
1042 to each debhelper command, which is generally better than using
1043 DH_OPTIONS.
1044 DH_ALWAYS_EXCLUDE
1046 If set, this adds the value the variable is set to to the -X
1047 options of all commands that support the -X option. Moreover,
1048 dh_builddeb will rm -rf anything that matches the value in your
1049 package build tree.
1050 This can be useful if you are doing a build from a CVS source tree,
1052 in which case setting DH_ALWAYS_EXCLUDE=CVS will prevent any CVS
1053 directories from sneaking into the package you build. Or, if a
1054 package has a source tarball that (unwisely) includes CVS
1055 directories, you might want to export DH_ALWAYS_EXCLUDE=CVS in
1056 debian/rules, to make it take effect wherever your package is
1057 built.
1058 Multiple things to exclude can be separated with colons, as in
1060 DH_ALWAYS_EXCLUDE=CVS:.svn
1061 DH_EXTRA_ADDONS
1063 If set, this adds the specified dh addons to be run in the
1064 appropriate places in the sequence of commands. This is equivalent
1065 to specifying the addon to run with the --with flag in the
1066 debian/rules file. Any --without calls specifying an addon in this
1067 environment variable will not be run.
1068 This is intended to be used by downstreams or specific local
1070 configurations that require a debhelper addon to be run during
1071 multiple builds without having to patch a large number of rules
1072 file. If at all possible, this should be avoided in favor of a
1073 --with flag in the rules file.
1074
1076 /usr/share/doc/debhelper/examples/
1077 A set of example debian/rules files that use debhelper.
1078 <http://joeyh.name/code/debhelper/>
1080 Debhelper web site.
1081
1083 Joey Hess <joeyh@debian.org>
108411.4 2019-02-01 debhelper(7)