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 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 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 v13 This is the recommended mode of operation.
98 Changes from v12 are:
100 - The meson+ninja build system now uses meson test instead of
102 ninja test when running the test suite. Any override of
103 dh_auto_test that passes extra parameters to upstream test
104 runner should be reviewed as meson test is not command line
105 compatible with ninja test.
106 - All debhelper like tools based on the official debhelper
108 library (including dh and the official dh_* tools) no
109 longer accepts abbreviated command parameters. At the same
110 time, dh now optimizes out calls to redundant dh_* helpers
111 even when passed long command line options.
112 - The ELF related debhelper tools (dh_dwz, dh_strip,
114 dh_makeshlibs, dh_shlibdeps) are now only run for arch
115 dependent packages by default (i.e. they are excluded from
116 *-indep targets and are passed -a by default). If you need
117 them for *-indep targets, you can add an explicit Build-
118 Depends on dh-sequence-elf-tools.
119 - The third-party gradle build system (from gradle-debian-
121 helper package) now runs the upstream-provided test suite
122 automatically. To suppress such behavior, override
123 dh_auto_test.
124 - The dh_installman tool now aborts if it sees conflicting
126 definitions of a manpage. This typically happens if the
127 upstream build system is installing a compressed version
128 and the package lists an uncompressed version of the
129 manpage in debian/package.manpages. Often the easiest fix
130 is to remove the manpage from debian/package.manpages
131 (assuming both versions are identical).
132 - The dh_auto_* helpers now reset the environment variables
134 HOME and common XDG_* variable. Please see description of
135 the environment variables in "ENVIRONMENT" for how this is
136 handled.
137 This feature changed between debhelper 13 and debhelper
139 13.2.
140 - The dh command will now error if an override or hook target
142 for an obsolete command are present in debian/rules (e.g.
143 override_dh_systemd_enable:).
144 - The dh_missing command will now default to --fail-missing.
146 This can be reverted to a non-fatal warning by explicitly
147 passing --list-missing like it was in compat 12.
148 If you do not want the warning either, please omit the call
150 to dh_missing. If you use the dh command sequencer, then
151 you can do this by inserting an empty override target in
152 the debian/rules file of the relevant package. As an
153 example:
154 # Disable dh_missing
156 override_dh_missing:
157 - The dh command sequencer now runs dh_installtmpfiles in the
159 default sequence. The dh_installtmpfiles takes over
160 handling of tmpfiles.d configuration files. Related
161 functionality in dh_installsystemd is now disabled.
162 Note that dh_installtmpfiles responds to
164 debian/package.tmpfiles where dh_installsystemd used a name
165 without the trailing "s".
166 - Many dh_* tools now support limited variable expansion via
168 the ${foo} syntax. In many cases, this can be used to
169 reference paths that contain either spaces or
170 dpkg-architecture(1) values. While this can reduce the
171 need for dh-exec(1) in some cases, it is not a replacement
172 dh-exec(1) in general. If you need filtering, renaming,
173 etc., the package will still need dh-exec(1).
174 Please see "Substitutions in debhelper config files" for
176 syntax and available substitution variables. To dh_* tool
177 writers, substitution expansion occurs as a part of the
178 filearray and filedoublearray functions.
179 - The dh command sequencer will now skip all hook and
181 override targets for dh_auto_test, dh_dwz and dh_strip when
182 DEB_BUILD_OPTIONS lists the relevant nocheck / nostrip
183 options.
184 Any package relying on these targets to always be run
186 should instead move relevant logic out of those targets.
187 E.g. non-test related packaging code from
188 override_dh_auto_test would have to be moved to
189 execute_after_dh_auto_build or
190 execute_before_dh_auto_install.
191 - The cmake buildsystem now passes
193 -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON to cmake(1) to speed
194 up automatic installation process. If for some reason you
195 need previous behavior, override the flag:
196 dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...
198 v12 Changes from v11 are:
200 - The dh_makeshlibs tool now generates shlibs files with
202 versioned dependency by default. This means that
203 -VUpstream-Version (a.k.a. -V) is now the default.
204 If an unversioned dependency in the shlibs file is wanted,
206 this can be obtained by passing -VNone instead. However,
207 please see dh_makeshlibs(1) for the caveat of unversioned
208 dependencies.
209 - The -s (--same-arch) option is removed. Please use -a
211 (--arch) instead.
212 - Invoking dh_clean -k now causes an error instead of a
214 deprecation warning.
215 - The --no-restart-on-upgrade option in dh_installinit has
217 been removed. Please use the new name --no-stop-on-upgrade
218 - There was a bug in the doit (and similar) functions from
220 Debian::Debhelper::Dh_Lib that made them spawn a shell in
221 one particular circumstance. This bug is now removed and
222 will cause helpers that rely on the bug to fail with a
223 "command not found"-error.
224 - The --list-missing and --fail-missing in dh_install has
226 been removed. Please use dh_missing and its corresponding
227 options, which can also see the files installed by other
228 helpers.
229 - The dh_installinit helper no longer installs configuration
231 for the upstart init system. Instead, it will abort the
232 build if it finds an old upstart configuration file. The
233 error is there to remind the package maintainer to ensure
234 the proper removal of the conffiles shipped in previous
235 versions of the package (if any).
236 - The dh_installdeb tool will do basic validation of some
238 dpkg-maintscript-helper(1) commands and will error out if
239 the commands appear to be invalid.
240 - The dh_missing tool will now default to --list-missing.
242 - The dh_makeshlibs tool will now only pass libraries to
244 dpkg-gensymbols(1) if the ELF binary has a SONAME
245 (containing ".so").
246 - The dh_compress tool no longer compresses examples (i.e.
248 anything installed in </usr/share/doc/package/examples>.)
249 - The standard sequence in dh now includes dh_dwz and
251 dh_installinitramfs by default. This makes the dwz and
252 installinitramfs sequences obsolete and they will now fail
253 with an error. If you want to skip these commands, then
254 please insert an empty override target for them in
255 debian/rules (e.g. override_dh_dwz:)
256 - The build systems meson and autoconf no longer explicitly
258 set the --libexecdir variable and thus relies on the build
259 system default - which should be /usr/libexec (per FHS 3.0,
260 adopted in Debian Policy 4.1.5).
261 If a particular upstream package does not use the correct
263 default, the parameter can often be passed manually via
264 dh_auto_configure(1). E.g. via the following example:
265 override_dh_auto_configure:
267 dh_auto_configure -- --libexecdir=/usr/libexec
268 Note the -- before the --libexecdir parameter.
270 - Retroactively removed in debhelper/13.5:
272 The dh_installdeb tool would no longer installs the
274 maintainer provided conffiles file as it was deemed
275 unnecessary. However, the remove-on-upgrade from dpkg/1.20
276 made the file relevant again and dh_installdeb now installs
277 it again in compat levels 12+.
278 - The dh_installsystemd tool no longer relies on
280 dh_installinit for handling systemd services that have a
281 sysvinit alternative. Both tools must now be used in such
282 a case to ensure the service is properly started under both
283 sysvinit and systemd.
284 If you have an override for dh_installinit (e.g. to call it
286 with --no-start) then you will probably need one for
287 dh_installsystemd as well now.
288 This change makes dh_installinit inject a misc:Pre-Depends
290 for init-system-helpers (>= 1.54~). Please ensure that the
291 package lists ${misc:Pre-Depends} in its Pre-Depends field
292 before upgrading to compat 12.
293 - The third-party dh_golang tool (from dh-golang package) now
295 defaults on honoring DH_GOLANG_EXCLUDES variable for source
296 installation in -dev packages and not only during the
297 building process. Please set DH_GOLANG_EXCLUDES_ALL to
298 false to revert to the previous behaviour. See
299 Debian::Debhelper::Buildsystem::golang(3pm) for details and
300 examples.
301 - dh_installsystemduser is now included in the dh standard
303 sequence by default.
304 - The python-distutils buildsystem is now removed. Please
306 use the third-party build system pybuild instead.
307 v11 This mode is discouraged.
309 The compat 11 is discouraged for new packages as it suffers from
311 feature interaction between dh_installinit and dh_installsystemd
312 causing services to not run correctly in some cases. Please
313 consider using compatibility mode 10 or 12 instead. More details
314 about the issue are available in Debian#887904 and
315 <https://lists.debian.org/debian-release/2019/04/msg01442.html>.
316 Changes from v10 are:
318 - dh_installinit no longer installs service or tmpfile files,
320 nor generates maintainer scripts for those files. Please
321 use the new dh_installsystemd helper.
322 - The dh_systemd_enable and dh_systemd_start helpers have
324 been replaced by the new dh_installsystemd helper. For the
325 same reason, the systemd sequence for dh has also been
326 removed. If you need to disable the dh_installsystemd
327 helper tool, please use an empty override target.
328 Please note that the dh_installsystemd tool has a slightly
330 different behaviour in some cases (e.g. when using the
331 --name parameter).
332 - dh_installdirs no longer creates debian/package directories
334 unless explicitly requested (or it has to create a
335 subdirectory in it).
336 The vast majority of all packages will be unaffected by
338 this change.
339 - The makefile buildsystem now passes INSTALL="install
341 --strip-program=true" to make(1). Derivative buildsystems
342 (e.g. configure or cmake) are unaffected by this change.
343 - The autoconf buildsystem now passes --runstatedir=/run to
345 ./configure.
346 - The cmake buildsystem now passes
348 -DCMAKE_INSTALL_RUNSTATEDIR=/run to cmake(1).
349 - dh_installman will now prefer detecting the language from
351 the path name rather than the extension.
352 - dh_auto_install will now only create the destination
354 directory it needs. Previously, it would create the
355 package build directory for all packages. This will not
356 affect packages that only build with debhelper commands,
357 but it may expose bugs in commands not included in
358 debhelper.
359 - The helpers dh_installdocs, dh_installexamples,
361 dh_installinfo, and dh_installman now error out if their
362 config has a pattern that does not match anything or
363 reference a path that does not exist.
364 Known exceptions include building with the nodoc profile,
366 where the above tools will silently permit failed matches
367 where the patterns are used to specify documentation.
368 - The helpers dh_installdocs, dh_installexamples,
370 dh_installinfo, and dh_installman now accept the parameter
371 --sourcedir with same meaning as dh_install. Furthermore,
372 they now also fall back to debian/tmp like dh_install.
373 Migration note: A bug in debhelper 11 up to 11.1.5 made
375 dh_installinfo incorrectly ignore --sourcedir.
376 - The perl-makemaker and perl-build build systems no longer
378 pass -I. to perl. Packages that still need this behaviour
379 can emulate it by using the PERL5LIB environment variable.
380 E.g. by adding export PERL5LIB=. in their debian/rules file
381 (or similar).
382 - The PERL_USE_UNSAFE_INC environment variable is no longer
384 set by dh or any of the dh_auto_* tools. It was added as a
385 temporary work around to avoid a lot of packages failing to
386 build at the same time.
387 Note this item will eventually become obsolete as upstream
389 intends to drop support for the PERL_USE_UNSAFE_INC
390 environment variable. When perl drops support for it, then
391 this variable will be removed retroactively from existing
392 compat levels as well.
393 - The dh_makeshlibs helper will now exit with an error if
395 objdump returns a non-zero exit from analysing a given
396 file.
397 - The dh_installdocs and dh_installexamples tools may now
399 install most of the documentation in a different path to
400 comply with the recommendation from Debian policy ยง12.3
401 (since version 3.9.7).
402 Note that if a given source package only contains a single
404 binary package in debian/control or none of the packages
405 are -doc packages, then this change is not relevant for
406 that source package and you can skip to the next change.
407 By default, these tools will now attempt to determine a
409 "main package for the documentation" (called a doc-main-
410 package from here on) for every -doc package. If they find
411 such a doc-main-package, they will now install the
412 documentation into the path /usr/share/doc/doc-main-package
413 in the given doc package. I.e. the path can change but the
414 documentation is still shipped in the -doc package.
415 The --doc-main-package option can be used when the auto-
417 detection is insufficient or to reset the path to its
418 previous value if there is a reason to diverge from Debian
419 policy recommendation.
420 Some documentation will not be affected by this change.
422 These exceptions include the copyright file, changelog
423 files, README.Debian, etc. These files will still be
424 installed in the path /usr/share/doc/package.
425 - The dh_strip and dh_shlibdeps tools no longer uses filename
427 patterns to determine which files to process. Instead,
428 they open the file and look for an ELF header to determine
429 if a given file is an shared object or an ELF executable.
430 This change may cause the tools to process more files than
432 previously.
433 v10 Changes from v9 are:
435 - dh_installinit will no longer install a file named
437 debian/package as an init script.
438 - dh_installdocs will error out if it detects links created
440 with --link-doc between packages of architecture "all" and
441 non-"all" as it breaks binNMUs.
442 - dh_installdeb no longer installs a maintainer-provided
444 debian/package.shlibs file. This is now done by
445 dh_makeshlibs instead.
446 - dh_installwm refuses to create a broken package if no man
448 page can be found (required to register for the x-window-
449 manager alternative).
450 - Debhelper will default to --parallel for all buildsystems
452 that support parallel building. This can be disabled by
453 using either --no-parallel or passing --max-parallel with a
454 value of 1.
455 - The dh command will not accept any of the deprecated
457 "manual sequence control" parameters (--before, --after,
458 etc.). Please use override targets instead.
459 Retroactively applied to earlier compat levels: dh no
461 longer accepts any of these since debhelper/12.4.
462 - The dh command will no longer use log files to track which
464 commands have been run. The dh command still keeps track
465 of whether it already ran the "build" sequence and skip it
466 if it did.
467 The main effects of this are:
469 - With this, it is now easier to debug the install or/and
471 binary sequences because they can now trivially be re-
472 run (without having to do a full "clean and rebuild"
473 cycle)
474 - The main caveat is that dh_* now only keeps track of
476 what happened in a single override target. When all
477 the calls to a given dh_cmd command happens in the same
478 override target everything will work as before.
479 Example of where it can go wrong:
481 override_dh_foo:
483 dh_foo -pmy-pkg
484 override_dh_bar:
486 dh_bar
487 dh_foo --remaining
488 In this case, the call to dh_foo --remaining will also
490 include my-pkg, since dh_foo -pmy-pkg was run in a
491 separate override target. This issue is not limited to
492 --remaining, but also includes -a, -i, etc.
493 - The dh_installdeb command now shell-escapes the lines in
495 the maintscript config file. This was the original intent
496 but it did not work properly and packages have begun to
497 rely on the incomplete shell escaping (e.g. quoting file
498 names).
499 - The dh_installinit command now defaults to
501 --restart-after-upgrade. For packages needing the previous
502 behaviour, please use --no-restart-after-upgrade.
503 - The autoreconf sequence is now enabled by default. Please
505 pass --without autoreconf to dh if this is not desirable
506 for a given package
507 - The systemd sequence is now enabled by default. Please
509 pass --without systemd to dh if this is not desirable for a
510 given package.
511 - Retroactively removed: dh no longer creates the package
513 build directory when skipping running debhelper commands.
514 This will not affect packages that only build with
515 debhelper commands, but it may expose bugs in commands not
516 included in debhelper.
517 This compatibility feature had a bug since its inception in
519 debhelper/9.20130516 that made it fail to apply in compat 9
520 and earlier. As there has been no reports of issues caused
521 by this bug in those ~5 years, this item have been removed
522 rather than fixed.
523 v9 Changes from v8 are:
525 - Multiarch support. In particular, dh_auto_configure passes
527 multiarch directories to autoconf in --libdir and
528 --libexecdir.
529 - dh is aware of the usual dependencies between targets in
531 debian/rules. So, "dh binary" will run any build, build-
532 arch, build-indep, install, etc targets that exist in the
533 rules file. There's no need to define an explicit binary
534 target with explicit dependencies on the other targets.
535 - dh_strip compresses debugging symbol files to reduce the
537 installed size of -dbg packages.
538 - dh_auto_configure does not include the source package name
540 in --libexecdir when using autoconf.
541 - dh does not default to enabling --with=python-support
543 (Obsolete: As the dh_pysupport tool was removed from Debian
545 stretch. Since debhelper/10.3, dh no longer enables this
546 sequence add-on regardless of compat level)
547 - All of the dh_auto_* debhelper programs and dh set
549 environment variables listed by dpkg-buildflags, unless
550 they are already set.
551 - dh_auto_configure passes dpkg-buildflags CFLAGS, CPPFLAGS,
553 and LDFLAGS to perl Makefile.PL and Build.PL
554 - dh_strip puts separated debug symbols in a location based
556 on their build-id.
557 - Executable debhelper config files are run and their output
559 used as the configuration.
560 This mode is deprecated.
562 v8 Changes from v7 are:
564 - Commands will fail rather than warning when they are passed
566 unknown options.
567 - dh_makeshlibs will run dpkg-gensymbols on all shared
569 libraries that it generates shlibs files for. So -X can be
570 used to exclude libraries. Also, libraries in unusual
571 locations that dpkg-gensymbols would not have processed
572 before will be passed to it, a behavior change that can
573 cause some packages to fail to build.
574 - dh requires the sequence to run be specified as the first
576 parameter, and any switches come after it. Ie, use "dh $@
577 --foo", not "dh --foo $@".
578 - dh_auto_* prefer to use Perl's Module::Build in preference
580 to Makefile.PL.
581 This mode is deprecated.
583 v7 This mode is deprecated.
585 This is the lowest supported compatibility level.
587 If you are upgrading from an earlier compatibility level, please
589 review debhelper-obsolete-compat(7).
590
592 debhelper-obsolete-compat(7)
593 Upgrading from a (now) obsolete compatibility level? This document
594 covers the upgrade checklist up to the earliest supported level.
595 debhelper(7)
597 General information about the debhelper framework. This document
598 also covers how to declare your chosen debhelper compat level.
599
601 Niels Thykier <niels@thykier.net>
602 Joey Hess
60413.11.4 2023-01-22 debhelper(7)