diff options
Diffstat (limited to 'debhelper-compat-upgrade-checklist.pod')
| -rw-r--r-- | debhelper-compat-upgrade-checklist.pod | 775 |
1 files changed, 775 insertions, 0 deletions
diff --git a/debhelper-compat-upgrade-checklist.pod b/debhelper-compat-upgrade-checklist.pod new file mode 100644 index 0000000..c55b1bd --- /dev/null +++ b/debhelper-compat-upgrade-checklist.pod @@ -0,0 +1,775 @@ +=encoding UTF-8 + +=head1 NAME + +debhelper-compat-upgrade-checklist - Upgrade checklist for supported debhelper compat levels + +=head1 SYNOPSIS + +This document is an upgrade checklist of all the supported debhelper compat levels. It also +lists all the support debhelper compat levels. + +Information about how to declare the compat level is in L<debhelper(7)/COMPATIBILITY LEVELS>. + +If you are upgrading from a (now) obsolete compat level, then please refer to +L<debhelper-obsolete-compat(7)>. + +=head1 DESCRIPTION + +=head2 Upgrade checklist for supported compatibility levels + +These are the available compatibility levels: + +=over 4 + +=item v15 + +This compatibility level is still open for development; use with caution. + +Changes from v14 are: + +=over 8 + +=item - + +The B<dh_auto_install> tool no longer defaults to B<< --destdir=debian/I<package> >> +for source packages only producing a single binary. If this behaviour is wanted, +the package should explicitly activate the B<single-binary> dh addon (e.g., by adding +B<dh-sequence-single-binary> to B<Build-Depends>) or pass B<--destdir> to +B<dh_auto_install>. + +The rationale for this change to avoid "surprises" when adding a second binary package +later. Previously, debhelper would silently change behaviour often resulting in empty +binary packages being uploaded to the archive by mistake. With the new behaviour, +the B<single-binary> addon will detect the mismatch and warn the maintainer of what is +about to happen. + +=back + +=item v14 + +This compatibility level is still open for development; use with caution. + +Changes from v13 are: + +=over 8 + +=item - + +The B<cmake> buildsystem now passes +B<-DCMAKE_BUILD_RPATH_USE_ORIGIN=ON> to L<cmake(1)> to avoid some +reproducibility issues. + +=item - + +The tool B<dh_installsysusers> is now included in the default sequence. This +helper tool will process systemd sysusers files. + +=item - + +Use of the B<dh_gconf> command in override and hook targets now causes +an error. The B<dh_gconf> command has been a no-op for years and was +removed in debhelper 13.4. + +=item - + +The B<dh> sequencer will warn if the B<single-binary> addon is implicitly activated to +warn maintainers of the pending compat 15 change in B<dh_auto_install>. + +Maintainers are urged to either explicitly activate the B<single-binary> addon to +preserve the existing behaviour (e.g., by adding B<dh-sequence-single-binary> to +Build-Depends), or explicitly passing B<--destdir> to B<dh_auto_install> if used and +then passing B<--without single-binary> to B<dh> (the latter to silence the warning). + +The rationale for this change to avoid "surprises" when adding a second binary package +later. Previously, debhelper would silently change behaviour often resulting in empty +binary packages being uploaded to the archive by mistake. With the new behaviour, +the B<single-binary> addon will detect the mismatch and warn the maintainer of what is +about to happen. + +=item - + +The B<dh_installalternatives> tool will now be run after B<dh_link> rather than after +B<dh_installinitramfs> in the default B<dh> sequence. + +=item - + +The B<dh_installpam> tool will now install PAM configuration files under +F<< /usr/lib/pam.d/I<package> >> instead of F<< /etc/pam.d/I<package> >>. + +Please consider using the "rm_conffile" feature from +L<dh_installdeb(1)> to ensure the proper removal of previous PAM files. + +=item - + +The B<meson+ninja> and B<cmake> build systems now use B<meson install> and +B<cmake --install>, respectively, instead of B<ninja install> and B<make install> +in the L<dh_auto_install(1)> call. Any override of B<dh_auto_install> that +passes extra parameters to the upstream build system should be reviewed. + +=back + +=item v13 + +This is the recommended mode of operation. + +Changes from v12 are: + +=over 8 + +=item - + +The B<meson+ninja> build system now uses B<meson test> instead of +B<ninja test> when running the test suite. Any override of +B<dh_auto_test> that passes extra parameters to upstream test runner +should be reviewed as B<meson test> is not command line compatible +with B<ninja test>. + +=item - + +All debhelper like tools based on the official debhelper library +(including B<dh> and the official B<dh_*> tools) no longer accepts +abbreviated command parameters. At the same time, B<dh> now +optimizes out calls to redundant B<dh_*> helpers even when passed +long command line options. + +=item - + +The ELF related debhelper tools (B<dh_dwz>, B<dh_strip>, +B<dh_makeshlibs>, B<dh_shlibdeps>) are now only run for arch dependent +packages by default (i.e. they are excluded from B<*-indep> targets +and are passed B<-a> by default). If you need them for B<*-indep> +targets, you can add an explicit Build-Depends on +B<dh-sequence-elf-tools>. + +=item - + +The third-party B<gradle> build system (from B<gradle-debian-helper> +package) now runs the upstream-provided test suite automatically. To +suppress such behavior, override B<dh_auto_test>. + +=item - + +The B<dh_installman> tool now aborts if it sees conflicting +definitions of a manpage. This typically happens if the upstream +build system is installing a compressed version and the package lists +an uncompressed version of the manpage in F<< +debian/I<package>.manpages >>. Often the easiest fix is to remove the +manpage from F<< debian/I<package>.manpages >> (assuming both versions +are identical). + +=item - + +The B<dh_auto_*> helpers now reset the environment variables B<HOME> +and common B<XDG_*> variable. Please see description of the +environment variables in L</ENVIRONMENT> for how this is handled. + +I<This feature changed between debhelper 13 and debhelper 13.2.> + +=item - + +The B<dh> command will now error if an override or hook target for an +obsolete command are present in F<debian/rules> +(e.g. B<override_dh_systemd_enable:>). + +=item - + +The B<dh_missing> command will now default to B<--fail-missing>. This +can be reverted to a non-fatal warning by explicitly passing +B<--list-missing> like it was in compat 12. + +If you do not want the warning either, please omit the call to +B<dh_missing>. If you use the B<dh> command sequencer, then you can +do this by inserting an empty override target in the +F<debian/rules> file of the relevant package. As an example: + + # Disable dh_missing + override_dh_missing: + +=item - + +The B<dh> command sequencer now runs B<dh_installtmpfiles> in the +default sequence. The B<dh_installtmpfiles> takes over handling of +tmpfiles.d configuration files. Related functionality in +B<dh_installsystemd> is now disabled. + +Note that B<dh_installtmpfiles> responds to +F<< debian/I<package>.tmpfiles >> where B<dh_installsystemd> used +a name without the trailing "s". + +=item - + +Many B<dh_*> tools now support limited variable expansion via the +B<${foo}> syntax. In many cases, this can be used to reference paths +that contain either spaces or L<dpkg-architecture(1)> values. While +this can reduce the need for L<dh-exec(1)> in some cases, it is B<not> +a replacement L<dh-exec(1)> in general. If you need filtering, +renaming, etc., the package will still need L<dh-exec(1)>. + +Please see L</Substitutions in debhelper config files> for syntax and +available substitution variables. To B<dh_*> tool writers, substitution +expansion occurs as a part of the B<filearray> and B<filedoublearray> +functions. + +=item - + +The B<dh> command sequencer will now skip all hook and override targets +for B<dh_auto_test>, B<dh_dwz> and B<dh_strip> when B<DEB_BUILD_OPTIONS> +lists the relevant B<nocheck> / B<nostrip> options. + +Any package relying on these targets to always be run should instead +move relevant logic out of those targets. E.g. non-test related +packaging code from B<override_dh_auto_test> would have to be moved to +B<execute_after_dh_auto_build> or B<execute_before_dh_auto_install>. + +=item - + +The B<cmake> buildsystem now passes B<-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON> +to L<cmake(1)> to speed up automatic installation process. If for some reason +you need previous behavior, override the flag: + + dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ... + +=back + +=item v12 + +Changes from v11 are: + +=over 8 + +=item - + +The B<dh_makeshlibs> tool now generates shlibs files with versioned +dependency by default. This means that B<-VUpstream-Version> +(a.k.a. B<-V>) is now the default. + +If an unversioned dependency in the shlibs file is wanted, this can be +obtained by passing B<-VNone> instead. However, please see +L<dh_makeshlibs(1)> for the caveat of unversioned dependencies. + +=item - + +The B<-s> (B<--same-arch>) option is removed. Please use B<-a> (B<--arch>) instead. + +=item - + +Invoking B<dh_clean -k> now causes an error instead of a deprecation +warning. + +=item - + +The B<--no-restart-on-upgrade> option in B<dh_installinit> has been removed. +Please use the new name B<--no-stop-on-upgrade> + +=item - + +There was a bug in the B<doit> (and similar) functions from +L<Debian::Debhelper::Dh_Lib> that made them spawn a shell in one +particular circumstance. This bug is now removed and will cause +helpers that rely on the bug to fail with a "command not found"-error. + +=item - + +The B<--list-missing> and B<--fail-missing> in B<dh_install> has been +removed. Please use B<dh_missing> and its corresponding options, +which can also see the files installed by other helpers. + +=item - + +The B<dh_installinit> helper no longer installs configuration for +the upstart init system. Instead, it will abort the build if it +finds an old upstart configuration file. The error is there to +remind the package maintainer to ensure the proper removal of the +conffiles shipped in previous versions of the package (if any). + +=item - + +The B<dh_installdeb> tool will do basic validation of some +L<dpkg-maintscript-helper(1)> commands and will error out if the +commands appear to be invalid. + +=item - + +The B<dh_missing> tool will now default to B<--list-missing>. + +=item - + +The B<dh_makeshlibs> tool will now only pass libraries to L<dpkg-gensymbols(1)> +if the ELF binary has a SONAME (containing ".so"). + +=item - + +The B<dh_compress> tool no longer compresses examples (i.e. anything installed +in F<</usr/share/doc/I<package>/examples>>.) + +=item - + +The standard sequence in B<dh> now includes B<dh_dwz> and +B<dh_installinitramfs> by default. This makes the B<dwz> and +B<installinitramfs> sequences obsolete and they will now fail with an +error. If you want to skip these commands, then please insert an +empty override target for them in F<debian/rules> +(e.g. I<override_dh_dwz:>) + +=item - + +The build systems B<meson> and B<autoconf> no longer explicitly set +the B<--libexecdir> variable and thus relies on the build system +default - which should be B</usr/libexec> (per FHS 3.0, adopted in +Debian Policy 4.1.5). + +If a particular upstream package does not use the correct default, the +parameter can often be passed manually via L<dh_auto_configure(1)>. E.g. +via the following example: + + override_dh_auto_configure: + dh_auto_configure -- --libexecdir=/usr/libexec + +Note the B<--> before the B<--libexecdir> parameter. + +=item - + +B<Retroactively removed in debhelper/13.5>: + +The B<dh_installdeb> tool would no longer installs the maintainer provided +F<conffiles> file as it was deemed unnecessary. However, the +B<remove-on-upgrade> from dpkg/1.20 made the file relevant again and +B<dh_installdeb> now installs it again in compat levels 12+. + +=item - + +The B<dh_installsystemd> tool no longer relies on B<dh_installinit> for +handling systemd services that have a sysvinit alternative. Both tools +must now be used in such a case to ensure the service is properly started +under both sysvinit and systemd. + +If you have an override for B<dh_installinit> (e.g. to call it with +B<--no-start>) then you will probably need one for +B<dh_installsystemd> as well now. + +This change makes B<dh_installinit> inject a I<misc:Pre-Depends> for +B<< init-system-helpers (>= 1.54~) >>. Please ensure that the package +lists B<${misc:Pre-Depends}> in its B<Pre-Depends> field before +upgrading to compat 12. + +=item - + +The third-party B<dh_golang> tool (from B<dh-golang> package) now defaults on +honoring B<DH_GOLANG_EXCLUDES> variable for source installation in -dev +packages and not only during the building process. Please set +B<DH_GOLANG_EXCLUDES_ALL> to false to revert to the previous behaviour. See +B<Debian::Debhelper::Buildsystem::golang(3pm)> for details and examples. + +=item - + +B<dh_installsystemduser> is now included in the B<dh> standard +sequence by default. + +=item - + +The B<python-distutils> buildsystem is now removed. Please use the +third-party build system B<pybuild> instead. + +=back + +=item v11 + +This mode is discouraged. + +The compat 11 is discouraged for new packages as it suffers from +feature interaction between L<dh_installinit> and L<dh_installsystemd> +causing services to not run correctly in some cases. Please consider +using compatibility mode 10 or 12 instead. More details about the +issue are available in Debian#887904 and +L<https://lists.debian.org/debian-release/2019/04/msg01442.html>. + +Changes from v10 are: + +=over 8 + +=item - + +B<dh_installinit> no longer installs F<service> or F<tmpfile> files, +nor generates maintainer scripts for those files. Please use the new +B<dh_installsystemd> helper. + +=item - + +The B<dh_systemd_enable> and B<dh_systemd_start> helpers have been +replaced by the new B<dh_installsystemd> helper. For the same reason, +the B<systemd> sequence for B<dh> has also been removed. If you need +to disable the B<dh_installsystemd> helper tool, please use an empty +override target. + +Please note that the B<dh_installsystemd> tool has a slightly +different behaviour in some cases (e.g. when using the B<--name> +parameter). + +=item - + +B<dh_installdirs> no longer creates debian/I<package> directories +unless explicitly requested (or it has to create a subdirectory in +it). + +The vast majority of all packages will be unaffected by this change. + +=item - + +The B<makefile> buildsystem now passes B<INSTALL="install +--strip-program=true"> to L<make(1)>. Derivative buildsystems +(e.g. B<configure> or B<cmake>) are unaffected by this change. + +=item - + +The B<autoconf> buildsystem now passes B<--runstatedir=/run> to +F<./configure>. + +=item - + +The B<cmake> buildsystem now passes +B<-DCMAKE_INSTALL_RUNSTATEDIR=/run> to L<cmake(1)>. + +=item - + +B<dh_installman> will now prefer detecting the language from the +path name rather than the extension. + +=item - + +B<dh_auto_install> will now only create the destination +directory it needs. Previously, it would create the package build +directory for all packages. This will not affect packages that only +build with debhelper commands, but it may expose bugs in commands not +included in debhelper. + +=item - + +The helpers B<dh_installdocs>, B<dh_installexamples>, B<dh_installinfo>, +and B<dh_installman> now error out if their config has a pattern that +does not match anything or reference a path that does not exist. + +Known exceptions include building with the B<nodoc> profile, where the +above tools will silently permit failed matches where the patterns +are used to specify documentation. + +=item - + +The helpers B<dh_installdocs>, B<dh_installexamples>, B<dh_installinfo>, +and B<dh_installman> now accept the parameter B<--sourcedir> with same +meaning as B<dh_install>. Furthermore, they now also fall back to +F<debian/tmp> like B<dh_install>. + +Migration note: A bug in debhelper 11 up to 11.1.5 made +B<dh_installinfo> incorrectly ignore B<--sourcedir>. + +=item - + +The B<perl-makemaker> and B<perl-build> build systems no longer pass +B<-I.> to perl. Packages that still need this behaviour can emulate +it by using the B<PERL5LIB> environment variable. E.g. by adding +B<export PERL5LIB=.> in their debian/rules file (or similar). + +=item - + +The B<PERL_USE_UNSAFE_INC> environment variable is no longer set by +B<dh> or any of the B<dh_auto_*> tools. It was added as a temporary +work around to avoid a lot of packages failing to build at the same +time. + +Note this item will eventually become obsolete as upstream intends +to drop support for the B<PERL_USE_UNSAFE_INC> environment variable. +When perl drops support for it, then this variable will be removed +retroactively from existing compat levels as well. + +=item - + +The B<dh_makeshlibs> helper will now exit with an error if objdump +returns a non-zero exit from analysing a given file. + +=item - + +The B<dh_installdocs> and B<dh_installexamples> tools may now install +I<most> of the documentation in a different path to comply with the +recommendation from Debian policy ยง12.3 (since version 3.9.7). + +Note that if a given source package only contains a single binary +package in F<debian/control> or none of the packages are I<-doc> +packages, then this change is not relevant for that source package and +you can skip to the next change. + +By default, these tools will now attempt to determine a "main package +for the documentation" (called a I<doc-main-package> from here on) for +every I<-doc> package. If they find such a I<doc-main-package>, they +will now install the documentation into the path F<< +/usr/share/doc/I<doc-main-package> >> in the given doc package. +I.e. the path can change but the documentation is still shipped in the +I<-doc> package. + +The B<--doc-main-package> option can be used when the auto-detection +is insufficient or to reset the path to its previous value if there is +a reason to diverge from Debian policy recommendation. + +Some documentation will not be affected by this change. These +exceptions include the copyright file, changelog files, README.Debian, +etc. These files will still be installed in the path F<< +/usr/share/doc/I<package> >>. + +=item - + +The B<dh_strip> and B<dh_shlibdeps> tools no longer uses filename +patterns to determine which files to process. Instead, they open the +file and look for an ELF header to determine if a given file is an +shared object or an ELF executable. + +This change may cause the tools to process more files than previously. + +=back + +=item v10 + +Changes from v9 are: + +=over 8 + +=item - + +B<dh_installinit> will no longer install a file named debian/I<package> +as an init script. + +=item - + +B<dh_installdocs> will error out if it detects links created with +--link-doc between packages of architecture "all" and non-"all" as it +breaks binNMUs. + +=item - + +B<dh_installdeb> no longer installs a maintainer-provided +debian/I<package>.shlibs file. This is now done by B<dh_makeshlibs> +instead. + +=item - + +B<dh_installwm> refuses to create a broken package if no man page +can be found (required to register for the x-window-manager alternative). + +=item - + +Debhelper will default to B<--parallel> for all buildsystems that +support parallel building. This can be disabled by using either +B<--no-parallel> or passing B<--max-parallel> with a value of 1. + +=item - + +The B<dh> command will not accept any of the deprecated "manual +sequence control" parameters (B<--before>, B<--after>, etc.). Please +use override targets instead. + +B<Retroactively applied to earlier compat levels>: B<dh> no longer +accepts any of these since debhelper/12.4. + +=item - + +The B<dh> command will no longer use log files to track which commands +have been run. The B<dh> command I<still> keeps track of whether it +already ran the "build" sequence and skip it if it did. + +The main effects of this are: + +=over 4 + +=item - + +With this, it is now easier to debug the I<install> or/and I<binary> +sequences because they can now trivially be re-run (without having to +do a full "clean and rebuild" cycle) + +=item - + +The main caveat is that B<dh_*> now only keeps track of what happened +in a single override target. When all the calls to a given B<dh_cmd> +command happens in the same override target everything will work as +before. + +Example of where it can go wrong: + + override_dh_foo: + dh_foo -pmy-pkg + + override_dh_bar: + dh_bar + dh_foo --remaining + +In this case, the call to B<dh_foo --remaining> will I<also> include +I<my-pkg>, since B<dh_foo -pmy-pkg> was run in a separate override +target. This issue is not limited to B<--remaining>, but also includes +B<-a>, B<-i>, etc. + +=back + +=item - + +The B<dh_installdeb> command now shell-escapes the lines in the +F<maintscript> config file. This was the original intent but it did +not work properly and packages have begun to rely on the incomplete +shell escaping (e.g. quoting file names). + +=item - + +The B<dh_installinit> command now defaults to +B<--restart-after-upgrade>. For packages needing the previous +behaviour, please use B<--no-restart-after-upgrade>. + +=item - + +The B<autoreconf> sequence is now enabled by default. Please pass +B<--without autoreconf> to B<dh> if this is not desirable for a given +package + +=item - + +The B<systemd> sequence is now enabled by default. Please pass +B<--without systemd> to B<dh> if this is not desirable for a given +package. + +=item - + +B<Retroactively removed>: B<dh> no longer creates the package build +directory when skipping running debhelper commands. This will not +affect packages that only build with debhelper commands, but it may +expose bugs in commands not included in debhelper. + +This compatibility feature had a bug since its inception in +debhelper/9.20130516 that made it fail to apply in compat 9 and +earlier. As there has been no reports of issues caused by this bug in +those ~5 years, this item have been removed rather than fixed. + +=back + +=item v9 + +Changes from v8 are: + +=over 8 + +=item - + +Multiarch support. In particular, B<dh_auto_configure> passes +multiarch directories to autoconf in --libdir and --libexecdir. + +=item - + +dh is aware of the usual dependencies between targets in debian/rules. +So, "dh binary" will run any build, build-arch, build-indep, install, +etc targets that exist in the rules file. There's no need to define an +explicit binary target with explicit dependencies on the other targets. + +=item - + +B<dh_strip> compresses debugging symbol files to reduce the installed +size of -dbg packages. + +=item - + +B<dh_auto_configure> does not include the source package name +in --libexecdir when using autoconf. + +=item - + +B<dh> does not default to enabling --with=python-support + +(Obsolete: As the B<dh_pysupport> tool was removed from Debian +stretch. Since debhelper/10.3, B<dh> no longer enables this sequence +add-on regardless of compat level) + +=item - + +All of the B<dh_auto_>I<*> debhelper programs and B<dh> set +environment variables listed by B<dpkg-buildflags>, unless +they are already set. + +=item - + +B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and +LDFLAGS to perl F<Makefile.PL> and F<Build.PL> + +=item - + +B<dh_strip> puts separated debug symbols in a location based on their +build-id. + +=item - + +Executable debhelper config files are run and their output used as the +configuration. + +=back + +This mode is deprecated. + +=item v8 + +Changes from v7 are: + +=over 8 + +=item - + +Commands will fail rather than warning when they are passed unknown options. + +=item - + +B<dh_makeshlibs> will run B<dpkg-gensymbols> on all shared libraries that it +generates shlibs files for. So B<-X> can be used to exclude libraries. +Also, libraries in unusual locations that B<dpkg-gensymbols> would not +have processed before will be passed to it, a behavior change that +can cause some packages to fail to build. + +=item - + +B<dh> requires the sequence to run be specified as the first parameter, and +any switches come after it. Ie, use "B<dh $@ --foo>", not "B<dh --foo $@>". + +=item - + +B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefile.PL>. + +=back + +This mode is deprecated. + +=item v7 + +This mode is deprecated. + +This is the lowest supported compatibility level. + +If you are upgrading from an earlier compatibility level, please +review L<debhelper-obsolete-compat(7)>. + +=back + +=head1 SEE ALSO + +=over 4 + +=item L<debhelper-obsolete-compat(7)> + +Upgrading from a (now) obsolete compatibility level? This document covers the +upgrade checklist up to the earliest supported level. + +=item L<debhelper(7)> + +General information about the debhelper framework. This document also covers +how to declare your chosen debhelper compat level. + +=back + +=head1 AUTHORS + +Niels Thykier <niels@thykier.net> + +Joey Hess + +=cut |