1debhelper(7) Debhelper debhelper(7)
2
6 debhelper-compat-upgrade-checklist - Upgrade checklist for supported
7 debhelper compat levels
8
10 This document is an upgrade checklist of all the supported debhelper
11 compat levels. It also lists all the support debhelper compat levels.
12 Information about how to declare the compat level is in "COMPATIBILITY
14 LEVELS" in debhelper(7).
15 If you are upgrading from a (now) obsolete compat level, then please
17 refer to debhelper-obsolete-compat(7).
18
20 Upgrade checklist for supported compatibility levels
21 These are the available compatibility levels:
22 v7 This mode is deprecated.
24 This is the lowest supported compatibility level.
26 If you are upgrading from an earlier compatibility level, please
28 review debhelper-obsolete-compat(7).
29 v8 Changes from v7 are:
31 - Commands will fail rather than warning when they are passed
33 unknown options.
34 - dh_makeshlibs will run dpkg-gensymbols on all shared
36 libraries that it generates shlibs files for. So -X can be
37 used to exclude libraries. Also, libraries in unusual
38 locations that dpkg-gensymbols would not have processed
39 before will be passed to it, a behavior change that can
40 cause some packages to fail to build.
41 - dh requires the sequence to run be specified as the first
43 parameter, and any switches come after it. Ie, use "dh $@
44 --foo", not "dh --foo $@".
45 - dh_auto_* prefer to use Perl's Module::Build in preference
47 to Makefile.PL.
48 This mode is deprecated.
50 v9 Changes from v8 are:
52 - Multiarch support. In particular, dh_auto_configure passes
54 multiarch directories to autoconf in --libdir and
55 --libexecdir.
56 - dh is aware of the usual dependencies between targets in
58 debian/rules. So, "dh binary" will run any build, build-
59 arch, build-indep, install, etc targets that exist in the
60 rules file. There's no need to define an explicit binary
61 target with explicit dependencies on the other targets.
62 - dh_strip compresses debugging symbol files to reduce the
64 installed size of -dbg packages.
65 - dh_auto_configure does not include the source package name
67 in --libexecdir when using autoconf.
68 - dh does not default to enabling --with=python-support
70 (Obsolete: As the dh_pysupport tool was removed from Debian
72 stretch. Since debhelper/10.3, dh no longer enables this
73 sequence add-on regardless of compat level)
74 - All of the dh_auto_* debhelper programs and dh set
76 environment variables listed by dpkg-buildflags, unless
77 they are already set.
78 - dh_auto_configure passes dpkg-buildflags CFLAGS, CPPFLAGS,
80 and LDFLAGS to perl Makefile.PL and Build.PL
81 - dh_strip puts separated debug symbols in a location based
83 on their build-id.
84 - Executable debhelper config files are run and their output
86 used as the configuration.
87 This mode is deprecated.
89 v10 Changes from v9 are:
91 - dh_installinit will no longer install a file named
93 debian/package as an init script.
94 - dh_installdocs will error out if it detects links created
96 with --link-doc between packages of architecture "all" and
97 non-"all" as it breaks binNMUs.
98 - dh_installdeb no longer installs a maintainer-provided
100 debian/package.shlibs file. This is now done by
101 dh_makeshlibs instead.
102 - dh_installwm refuses to create a broken package if no man
104 page can be found (required to register for the x-window-
105 manager alternative).
106 - Debhelper will default to --parallel for all buildsystems
108 that support parallel building. This can be disabled by
109 using either --no-parallel or passing --max-parallel with a
110 value of 1.
111 - The dh command will not accept any of the deprecated
113 "manual sequence control" parameters (--before, --after,
114 etc.). Please use override targets instead.
115 Retroactively applied to earlier compat levels: dh no
117 longer accepts any of these since debhelper/12.4.
118 - The dh command will no longer use log files to track which
120 commands have been run. The dh command still keeps track
121 of whether it already ran the "build" sequence and skip it
122 if it did.
123 The main effects of this are:
125 - With this, it is now easier to debug the install or/and
127 binary sequences because they can now trivially be re-
128 run (without having to do a full "clean and rebuild"
129 cycle)
130 - The main caveat is that dh_* now only keeps track of
132 what happened in a single override target. When all
133 the calls to a given dh_cmd command happens in the same
134 override target everything will work as before.
135 Example of where it can go wrong:
137 override_dh_foo:
139 dh_foo -pmy-pkg
140 override_dh_bar:
142 dh_bar
143 dh_foo --remaining
144 In this case, the call to dh_foo --remaining will also
146 include my-pkg, since dh_foo -pmy-pkg was run in a
147 separate override target. This issue is not limited to
148 --remaining, but also includes -a, -i, etc.
149 - The dh_installdeb command now shell-escapes the lines in
151 the maintscript config file. This was the original intent
152 but it did not work properly and packages have begun to
153 rely on the incomplete shell escaping (e.g. quoting file
154 names).
155 - The dh_installinit command now defaults to
157 --restart-after-upgrade. For packages needing the previous
158 behaviour, please use --no-restart-after-upgrade.
159 - The autoreconf sequence is now enabled by default. Please
161 pass --without autoreconf to dh if this is not desirable
162 for a given package
163 - The systemd sequence is now enabled by default. Please
165 pass --without systemd to dh if this is not desirable for a
166 given package.
167 - Retroactively removed: dh no longer creates the package
169 build directory when skipping running debhelper commands.
170 This will not affect packages that only build with
171 debhelper commands, but it may expose bugs in commands not
172 included in debhelper.
173 This compatibility feature had a bug since its inception in
175 debhelper/9.20130516 that made it fail to apply in compat 9
176 and earlier. As there has been no reports of issues caused
177 by this bug in those ~5 years, this item have been removed
178 rather than fixed.
179 v11 This mode is discouraged.
181 The compat 11 is discouraged for new packages as it suffers from
183 feature interaction between dh_installinit and dh_installsystemd
184 causing services to not run correctly in some cases. Please
185 consider using compatibility mode 10 or 12 instead. More details
186 about the issue are available in Debian#887904 and
187 <https://lists.debian.org/debian-release/2019/04/msg01442.html>.
188 Changes from v10 are:
190 - dh_installinit no longer installs service or tmpfile files,
192 nor generates maintainer scripts for those files. Please
193 use the new dh_installsystemd helper.
194 - The dh_systemd_enable and dh_systemd_start helpers have
196 been replaced by the new dh_installsystemd helper. For the
197 same reason, the systemd sequence for dh has also been
198 removed. If you need to disable the dh_installsystemd
199 helper tool, please use an empty override target.
200 Please note that the dh_installsystemd tool has a slightly
202 different behaviour in some cases (e.g. when using the
203 --name parameter).
204 - dh_installdirs no longer creates debian/package directories
206 unless explicitly requested (or it has to create a
207 subdirectory in it).
208 The vast majority of all packages will be unaffected by
210 this change.
211 - The makefile buildsystem now passes INSTALL="install
213 --strip-program=true" to make(1). Derivative buildsystems
214 (e.g. configure or cmake) are unaffected by this change.
215 - The autoconf buildsystem now passes --runstatedir=/run to
217 ./configure.
218 - The cmake buildsystem now passes
220 -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
221 - dh_installman will now prefer detecting the language from
223 the path name rather than the extension.
224 - dh_auto_install will now only create the destination
226 directory it needs. Previously, it would create the
227 package build directory for all packages. This will not
228 affect packages that only build with debhelper commands,
229 but it may expose bugs in commands not included in
230 debhelper.
231 - The helpers dh_installdocs, dh_installexamples,
233 dh_installinfo, and dh_installman now error out if their
234 config has a pattern that does not match anything or
235 reference a path that does not exist.
236 Known exceptions include building with the nodoc profile,
238 where the above tools will silently permit failed matches
239 where the patterns are used to specify documentation.
240 - The helpers dh_installdocs, dh_installexamples,
242 dh_installinfo, and dh_installman now accept the parameter
243 --sourcedir with same meaning as dh_install. Furthermore,
244 they now also fall back to debian/tmp like dh_install.
245 Migration note: A bug in debhelper 11 up to 11.1.5 made
247 dh_installinfo incorrectly ignore --sourcedir.
248 - The perl-makemaker and perl-build build systems no longer
250 pass -I. to perl. Packages that still need this behaviour
251 can emulate it by using the PERL5LIB environment variable.
252 E.g. by adding export PERL5LIB=. in their debian/rules file
253 (or similar).
254 - The PERL_USE_UNSAFE_INC environment variable is no longer
256 set by dh or any of the dh_auto_* tools. It was added as a
257 temporary work around to avoid a lot of packages failing to
258 build at the same time.
259 Note this item will eventually become obsolete as upstream
261 intends to drop support for the PERL_USE_UNSAFE_INC
262 environment variable. When perl drops support for it, then
263 this variable will be removed retroactively from existing
264 compat levels as well.
265 - The dh_makeshlibs helper will now exit with an error if
267 objdump returns a non-zero exit from analysing a given
268 file.
269 - The dh_installdocs and dh_installexamples tools may now
271 install most of the documentation in a different path to
272 comply with the recommendation from Debian policy ยง12.3
273 (since version 3.9.7).
274 Note that if a given source package only contains a single
276 binary package in debian/control or none of the packages
277 are -doc packages, then this change is not relevant for
278 that source package and you can skip to the next change.
279 By default, these tools will now attempt to determine a
281 "main package for the documentation" (called a doc-main-
282 package from here on) for every -doc package. If they find
283 such a doc-main-package, they will now install the
284 documentation into the path /usr/share/doc/doc-main-package
285 in the given doc package. I.e. the path can change but the
286 documentation is still shipped in the -doc package.
287 The --doc-main-package option can be used when the auto-
289 detection is insufficient or to reset the path to its
290 previous value if there is a reason to diverge from Debian
291 policy recommendation.
292 Some documentation will not be affected by this change.
294 These exceptions include the copyright file, changelog
295 files, README.Debian, etc. These files will still be
296 installed in the path /usr/share/doc/package.
297 - The dh_strip and dh_shlibdeps tools no longer uses filename
299 patterns to determine which files to process. Instead,
300 they open the file and look for an ELF header to determine
301 if a given file is an shared object or an ELF executable.
302 This change may cause the tools to process more files than
304 previously.
305 v12 Changes from v11 are:
307 - The dh_makeshlibs tool now generates shlibs files with
309 versioned dependency by default. This means that
310 -VUpstream-Version (a.k.a. -V) is now the default.
311 If an unversioned dependency in the shlibs file is wanted,
313 this can be obtained by passing -VNone instead. However,
314 please see dh_makeshlibs(1) for the caveat of unversioned
315 dependencies.
316 - The -s (--same-arch) option is removed. Please use -a
318 (--arch) instead.
319 - Invoking dh_clean -k now causes an error instead of a
321 deprecation warning.
322 - The --no-restart-on-upgrade option in dh_installinit has
324 been removed. Please use the new name --no-stop-on-upgrade
325 - There was a bug in the doit (and similar) functions from
327 Debian::Debhelper::Dh_Lib that made them spawn a shell in
328 one particular circumstance. This bug is now removed and
329 will cause helpers that rely on the bug to fail with a
330 "command not found"-error.
331 - The --list-missing and --fail-missing in dh_install has
333 been removed. Please use dh_missing and its corresponding
334 options, which can also see the files installed by other
335 helpers.
336 - The dh_installinit helper no longer installs configuration
338 for the upstart init system. Instead, it will abort the
339 build if it finds an old upstart configuration file. The
340 error is there to remind the package maintainer to ensure
341 the proper removal of the conffiles shipped in previous
342 versions of the package (if any).
343 - The dh_installdeb tool will do basic validation of some
345 dpkg-maintscript-helper(1) commands and will error out if
346 the commands appear to be invalid.
347 - The dh_missing tool will now default to --list-missing.
349 - The dh_makeshlibs tool will now only pass libraries to
351 dpkg-gensymbols(1) if the ELF binary has a SONAME
352 (containing ".so").
353 - The dh_compress tool no longer compresses examples (i.e.
355 anything installed in </usr/share/doc/package/examples>.)
356 - The standard sequence in dh now includes dh_dwz and
358 dh_installinitramfs by default. This makes the dwz and
359 installinitramfs sequences obsolete and they will now fail
360 with an error. If you want to skip these commands, then
361 please insert an empty override target for them in
362 debian/rules (e.g. override_dh_dwz:)
363 - The build systems meson and autoconf no longer explicitly
365 set the --libexecdir variable and thus relies on the build
366 system default - which should be /usr/libexec (per FHS 3.0,
367 adopted in Debian Policy 4.1.5).
368 If a particular upstream package does not use the correct
370 default, the parameter can often be passed manually via
371 dh_auto_configure(1). E.g. via the following example:
372 override_dh_auto_configure:
374 dh_auto_configure -- --libexecdir=/usr/libexec
375 Note the -- before the --libexecdir parameter.
377 - Retroactively removed in debhelper/13.5:
379 The dh_installdeb tool would no longer installs the
381 maintainer provided conffiles file as it was deemed
382 unnecessary. However, the remove-on-upgrade from dpkg/1.20
383 made the file relevant again and dh_installdeb now installs
384 it again in compat levels 12+.
385 - The dh_installsystemd tool no longer relies on
387 dh_installinit for handling systemd services that have a
388 sysvinit alternative. Both tools must now be used in such
389 a case to ensure the service is properly started under both
390 sysvinit and systemd.
391 If you have an override for dh_installinit (e.g. to call it
393 with --no-start) then you will probably need one for
394 dh_installsystemd as well now.
395 This change makes dh_installinit inject a misc:Pre-Depends
397 for init-system-helpers (>= 1.54~). Please ensure that the
398 package lists ${misc:Pre-Depends} in its Pre-Depends field
399 before upgrading to compat 12.
400 - The third-party dh_golang tool (from dh-golang package) now
402 defaults on honoring DH_GOLANG_EXCLUDES variable for source
403 installation in -dev packages and not only during the
404 building process. Please set DH_GOLANG_EXCLUDES_ALL to
405 false to revert to the previous behaviour. See
406 Debian::Debhelper::Buildsystem::golang(3pm) for details and
407 examples.
408 - dh_installsystemduser is now included in the dh standard
410 sequence by default.
411 - The python-distutils buildsystem is now removed. Please
413 use the third-party build system pybuild instead.
414 v13 This is the recommended mode of operation.
416 Changes from v12 are:
418 - The meson+ninja build system now uses meson test instead of
420 ninja test when running the test suite. Any override of
421 dh_auto_test that passes extra parameters to upstream test
422 runner should be reviewed as meson test is not command line
423 compatible with ninja test.
424 - All debhelper like tools based on the official debhelper
426 library (including dh and the official dh_* tools) no
427 longer accepts abbreviated command parameters. At the same
428 time, dh now optimizes out calls to redundant dh_* helpers
429 even when passed long command line options.
430 - The ELF related debhelper tools (dh_dwz, dh_strip,
432 dh_makeshlibs, dh_shlibdeps) are now only run for arch
433 dependent packages by default (i.e. they are excluded from
434 *-indep targets and are passed -a by default). If you need
435 them for *-indep targets, you can add an explicit Build-
436 Depends on dh-sequence-elf-tools.
437 - The third-party gradle build system (from gradle-debian-
439 helper package) now runs the upstream-provided test suite
440 automatically. To suppress such behavior, override
441 dh_auto_test.
442 - The dh_installman tool now aborts if it sees conflicting
444 definitions of a manpage. This typically happens if the
445 upstream build system is installing a compressed version
446 and the package lists an uncompressed version of the
447 manpage in debian/package.manpages. Often the easiest fix
448 is to remove the manpage from debian/package.manpages
449 (assuming both versions are identical).
450 - The dh_auto_* helpers now reset the environment variables
452 HOME and common XDG_* variable. Please see description of
453 the environment variables in "ENVIRONMENT" for how this is
454 handled.
455 This feature changed between debhelper 13 and debhelper
457 13.2.
458 - The dh command will now error if an override or hook target
460 for an obsolete command are present in debian/rules (e.g.
461 override_dh_systemd_enable:).
462 - The dh_missing command will now default to --fail-missing.
464 This can be reverted to a non-fatal warning by explicitly
465 passing --list-missing like it was in compat 12.
466 If you do not want the warning either, please omit the call
468 to dh_missing. If you use the dh command sequencer, then
469 you can do this by inserting an empty override target in
470 the debian/rules file of the relevant package. As an
471 example:
472 # Disable dh_missing
474 override_dh_missing:
475 - The dh command sequencer now runs dh_installtmpfiles in the
477 default sequence. The dh_installtmpfiles takes over
478 handling of tmpfiles.d configuration files. Related
479 functionality in dh_installsystemd is now disabled.
480 Note that dh_installtmpfiles responds to
482 debian/package.tmpfiles where dh_installsystemd used a name
483 without the trailing "s".
484 - Many dh_* tools now support limited variable expansion via
486 the ${foo} syntax. In many cases, this can be used to
487 reference paths that contain either spaces or
488 dpkg-architecture(1) values. While this can reduce the
489 need for dh-exec(1) in some cases, it is not a replacement
490 dh-exec(1) in general. If you need filtering, renaming,
491 etc., the package will still need dh-exec(1).
492 Please see "Substitutions in debhelper config files" for
494 syntax and available substitution variables. To dh_* tool
495 writers, substitution expansion occurs as a part of the
496 filearray and filedoublearray functions.
497 - The dh command sequencer will now skip all hook and
499 override targets for dh_auto_test, dh_dwz and dh_strip when
500 DEB_BUILD_OPTIONS lists the relevant nocheck / nostrip
501 options.
502 Any package relying on these targets to always be run
504 should instead move relevant logic out of those targets.
505 E.g. non-test related packaging code from
506 override_dh_auto_test would have to be moved to
507 execute_after_dh_auto_build or
508 execute_before_dh_auto_install.
509 - The cmake buildsystem now passes
511 -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON to cmake(1) to speed
512 up automatic installation process. If for some reason you
513 need previous behavior, override the flag:
514 dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...
516 v14 This compatibility level is still open for development; use with
518 caution.
519 Changes from v13 are:
521 - The cmake buildsystem now passes -DCMAKE_SKIP_RPATH=ON and
523 -DCMAKE_BUILD_RPATH_USE_ORIGIN=ON to cmake(1) to avoid some
524 reproducibility issues.
525 This can cause issues with running binaries directly from
527 the build directories as they might now require a manually
528 set LD_LIBRARY_PATH. If you need to override this change,
529 we recommend that you try to pass the
530 -DCMAKE_SKIP_RPATH=OFF option first to see if that fixes
531 the problem (leaving CMAKE_BUILD_RPATH_USE_ORIGIN at its
532 new default). This should undo the need for
533 LD_LIBRARY_PATH and avoid the reproducibility issues on
534 Linux, where $ORIGIN is supported by the runtime linkers.
535 - The tool dh_installsysusers is now included in the default
537 sequence. It will cause units to be automatically started
538 on installation, restarted on upgrade and stopped on
539 removal for every systemd user instance running on the
540 system.
541 - Use of the dh_gconf command in override and hook targets
543 now causes an error. The dh_gconf command has been a no-op
544 for years and was removed in debhelper 13.4.
545 - The dh sequencer will warn if the single-binary addon is
547 implicitly activated to warn maintainers of the pending
548 compat 15 change in dh_auto_install.
549 Maintainers are urged to either explicitly activate the
551 single-binary addon to preserve the existing behaviour
552 (e.g., by adding dh-sequence-single-binary to Build-
553 Depends), or explicitly passing --destdir to
554 dh_auto_install if used and then passing --without single-
555 binary to dh (the latter to silence the warning).
556 The rationale for this change to avoid "surprises" when
558 adding a second binary package later. Previously,
559 debhelper would silently change behaviour often resulting
560 in empty binary packages being uploaded to the archive by
561 mistake. With the new behaviour, the single-binary addon
562 will detect the mismatch and warn the maintainer of what is
563 about to happen.
564 - The dh_installalternatives tool will now be run after
566 dh_link rather than after dh_installinitramfs in the
567 default dh sequence.
568 - The dh_installpam tool will now install PAM configuration
570 files under /usr/lib/pam.d/package instead of
571 /etc/pam.d/package.
572 Please consider using the "rm_conffile" feature from
574 dh_installdeb(1) to ensure the proper removal of previous
575 PAM files.
576 v15 This compatibility level is still open for development; use with
578 caution.
579 Changes from v14 are:
581 - The dh_auto_install tool no longer defaults to
583 --destdir=debian/package for source packages only producing
584 a single binary. If this behaviour is wanted, the package
585 should explicitly activate the single-binary dh addon
586 (e.g., by adding dh-sequence-single-binary to Build-
587 Depends) or pass --destdir to dh_auto_install.
588 The rationale for this change to avoid "surprises" when
590 adding a second binary package later. Previously,
591 debhelper would silently change behaviour often resulting
592 in empty binary packages being uploaded to the archive by
593 mistake. With the new behaviour, the single-binary addon
594 will detect the mismatch and warn the maintainer of what is
595 about to happen.
596
598 debhelper-obsolete-compat(7)
599 Upgrading from a (now) obsolete compatibility level? This document
600 covers the upgrade checklist up to the earliest supported level.
601 debhelper(7)
603 General information about the debhelper framework. This document
604 also covers how to declare your chosen debhelper compat level.
605
607 Niels Thykier <niels@thykier.net>
608 Joey Hess
61013.7.1 2022-04-22 debhelper(7)