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