diff options
Diffstat (limited to 'debhelper-compat-upgrade-checklist.pod')
| -rw-r--r-- | debhelper-compat-upgrade-checklist.pod | 694 |
1 files changed, 347 insertions, 347 deletions
diff --git a/debhelper-compat-upgrade-checklist.pod b/debhelper-compat-upgrade-checklist.pod index a4d16d5b..c55b1bd7 100644 --- a/debhelper-compat-upgrade-checklist.pod +++ b/debhelper-compat-upgrade-checklist.pod @@ -22,225 +22,354 @@ These are the available compatibility levels: =over 4 -=item v7 +=item v15 -This mode is deprecated. +This compatibility level is still open for development; use with caution. -This is the lowest supported compatibility level. +Changes from v14 are: -If you are upgrading from an earlier compatibility level, please -review L<debhelper-obsolete-compat(7)>. +=over 8 -=item v8 +=item - -Changes from v7 are: +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 - -Commands will fail rather than warning when they are passed unknown options. +The B<cmake> buildsystem now passes +B<-DCMAKE_BUILD_RPATH_USE_ORIGIN=ON> to L<cmake(1)> to avoid some +reproducibility issues. =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. +The tool B<dh_installsysusers> is now included in the default sequence. This +helper tool will process systemd sysusers files. =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 $@>". +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 - -B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefile.PL>. +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 -This mode is deprecated. +=item v13 -=item v9 +This is the recommended mode of operation. -Changes from v8 are: +Changes from v12 are: =over 8 -=item - +=item - -Multiarch support. In particular, B<dh_auto_configure> passes -multiarch directories to autoconf in --libdir and --libexecdir. +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 - -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. +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 - -B<dh_strip> compresses debugging symbol files to reduce the installed -size of -dbg packages. +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 - -B<dh_auto_configure> does not include the source package name -in --libexecdir when using autoconf. +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 - -B<dh> does not default to enabling --with=python-support +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). -(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 - + +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 - -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. +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 - -B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and -LDFLAGS to perl F<Makefile.PL> and F<Build.PL> +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 - -B<dh_strip> puts separated debug symbols in a location based on their -build-id. +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 - -Executable debhelper config files are run and their output used as the -configuration. +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)>. -=back +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. -This mode is deprecated. +=item - -=item v10 +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. -Changes from v9 are: +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 - -B<dh_installinit> will no longer install a file named debian/I<package> -as an init script. +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 - -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. +The B<-s> (B<--same-arch>) option is removed. Please use B<-a> (B<--arch>) instead. =item - -B<dh_installdeb> no longer installs a maintainer-provided -debian/I<package>.shlibs file. This is now done by B<dh_makeshlibs> -instead. +Invoking B<dh_clean -k> now causes an error instead of a deprecation +warning. =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). +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 - -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. +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<dh> command will not accept any of the deprecated "manual -sequence control" parameters (B<--before>, B<--after>, etc.). Please -use override targets instead. +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. -B<Retroactively applied to earlier compat levels>: B<dh> no longer -accepts any of these since debhelper/12.4. +=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> 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 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. -The main effects of this are: +=item - -=over 4 +The B<dh_missing> tool will now default to B<--list-missing>. =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) +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 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. +The B<dh_compress> tool no longer compresses examples (i.e. anything installed +in F<</usr/share/doc/I<package>/examples>>.) -Example of where it can go wrong: +=item - - override_dh_foo: - dh_foo -pmy-pkg +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:>) - override_dh_bar: - dh_bar - dh_foo --remaining +=item - -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. +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). -=back +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: -=item - + override_dh_auto_configure: + dh_auto_configure -- --libexecdir=/usr/libexec -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). +Note the B<--> before the B<--libexecdir> parameter. =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>. +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<autoreconf> sequence is now enabled by default. Please pass -B<--without autoreconf> to B<dh> if this is not desirable for a given -package +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 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. +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<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. +B<dh_installsystemduser> is now included in the B<dh> standard +sequence by default. -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. +=item - + +The B<python-distutils> buildsystem is now removed. Please use the +third-party build system B<pybuild> instead. =back @@ -397,356 +526,227 @@ This change may cause the tools to process more files than previously. =back -=item v12 +=item v10 -Changes from v11 are: +Changes from v9 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. +B<dh_installinit> will no longer install a file named debian/I<package> +as an init script. =item - -Invoking B<dh_clean -k> now causes an error instead of a deprecation -warning. +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 - -The B<--no-restart-on-upgrade> option in B<dh_installinit> has been removed. -Please use the new name B<--no-stop-on-upgrade> +B<dh_installdeb> no longer installs a maintainer-provided +debian/I<package>.shlibs file. This is now done by B<dh_makeshlibs> +instead. =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. +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 - -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. +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_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> command will not accept any of the deprecated "manual +sequence control" parameters (B<--before>, B<--after>, etc.). Please +use override targets instead. -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. +B<Retroactively applied to earlier compat levels>: B<dh> no longer +accepts any of these since debhelper/12.4. =item - -The B<dh_missing> tool will now default to B<--list-missing>. +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. -=item - +The main effects of this are: -The B<dh_makeshlibs> tool will now only pass libraries to L<dpkg-gensymbols(1)> -if the ELF binary has a SONAME (containing ".so"). +=over 4 =item - -The B<dh_compress> tool no longer compresses examples (i.e. anything installed -in F<</usr/share/doc/I<package>/examples>>.) +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 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:>) +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. -=item - +Example of where it can go wrong: -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). + override_dh_foo: + dh_foo -pmy-pkg -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_bar: + dh_bar + dh_foo --remaining - override_dh_auto_configure: - dh_auto_configure -- --libexecdir=/usr/libexec +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. -Note the B<--> before the B<--libexecdir> parameter. +=back =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+. +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_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. +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 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. +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 - -B<dh_installsystemduser> is now included in the B<dh> standard -sequence by default. +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 - -The B<python-distutils> buildsystem is now removed. Please use the -third-party build system B<pybuild> instead. +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. -=back +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. -=item v13 +=back -This is the recommended mode of operation. +=item v9 -Changes from v12 are: +Changes from v8 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>. +Multiarch support. In particular, B<dh_auto_configure> passes +multiarch directories to autoconf in --libdir and --libexecdir. =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). +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 - -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.> +B<dh_strip> compresses debugging symbol files to reduce the installed +size of -dbg packages. =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:>). +B<dh_auto_configure> does not include the source package name +in --libexecdir when using autoconf. =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: +B<dh> does not default to enabling --with=python-support - # Disable dh_missing - override_dh_missing: +(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 - -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". +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 - -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. +B<dh_auto_configure> passes B<dpkg-buildflags> CFLAGS, CPPFLAGS, and +LDFLAGS to perl F<Makefile.PL> and F<Build.PL> =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>. +B<dh_strip> puts separated debug symbols in a location based on their +build-id. =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 ... +Executable debhelper config files are run and their output used as the +configuration. =back -=item v14 +This mode is deprecated. -This compatibility level is still open for development; use with caution. +=item v8 -Changes from v13 are: +Changes from v7 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. +Commands will fail rather than warning when they are passed unknown options. =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. +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 - -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. +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 - -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. +B<dh_auto_>I<*> prefer to use Perl's B<Module::Build> in preference to F<Makefile.PL>. =back -=item v15 - -This compatibility level is still open for development; use with caution. - -Changes from v14 are: - -=over 8 +This mode is deprecated. -=item - +=item v7 -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>. +This mode is deprecated. -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. +This is the lowest supported compatibility level. -=back +If you are upgrading from an earlier compatibility level, please +review L<debhelper-obsolete-compat(7)>. =back |