Merge https://salsa.debian.org/debian/debhelper

1 files changed, 170 insertions, 27 deletions

diff --git a/debhelper.pod b/debhelper.pod
index acdda660..e850ef5c 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -30,8 +30,8 @@ package contains a tutorial about making your first package using debhelper.
 
 Except where tool explicitly denotes otherwise, all of the debhelper
 tools assumes that they run from root directory of an unpacked source
-package.  This is so they can locate find F<debian/control> and
-F<debian/compat> when needed.
+package.  This is so they can locate find files like F<debian/control>
+when needed.
 
 =head1 DEBHELPER COMMANDS
 
@@ -254,13 +254,13 @@ B<dh_auto_>I<*> programs.
 Force use of the specified I<buildsystem>, instead of trying to auto-select
 one which might be applicable for the package.
 
-=item B<-D>I<directory>, B<--sourcedirectory=>I<directory>
+=item B<-D>I<directory>, B<--sourcedir=>I<directory>, B<--sourcedirectory=>I<directory>
 
 Assume that the original package source tree is at the specified
 I<directory> rather than the top level directory of the Debian
 source package tree.
 
-=item B<-B>[I<directory>], B<--builddirectory=>[I<directory>]
+=item B<-B>[I<directory>], B<--builddir>[I<=directory>], B<--builddirectory>[I<=directory>]
 
 Enable out of source building and use the specified I<directory> as the build
 directory. If I<directory> parameter is omitted, a default build directory
@@ -301,6 +301,37 @@ level that is known to work, or that you wish to support.
 Notably, setting the maximum to 1 is effectively the same as using
 B<--no-parallel>.
 
+=item B<--reload-all-buildenv-variables>
+
+By default, L<dh(1)> will compute several environment (e.g. by using
+L<dpkg-buildflags(1)>) and cache them to avoid having all B<dh_auto_*>
+tool recompute them.
+
+When passing this option, the concrete B<dh_auto_*> tool will ignore
+the cache from L<dh(1)> and retrigger a rebuild of these variables.
+This is useful in the very rare case where the package need to do
+multiple builds but with different B<...FLAGS> options.  A concrete
+example would be needing to change the B<-O> parameter in B<CFLAGS> in
+the second build:
+
+    export DEB_CFLAGS_MAINT_APPEND=-O3
+
+    %:
+        dh $@
+
+    override_dh_auto_configure:
+        dh_auto_configure -Bbuild-deb ...
+        DEB_CFLAGS_MAINT_APPEND=-Os dh_auto_configure \
+           --reload-all-buildenv-variables -Bbuild-udeb ...
+
+Without B<--reload-all-buildenv-variables> in the second call to
+L<dh_auto_configure(1)>, the change in B<DEB_CFLAGS_MAINT_APPEND>
+would be ignored as L<dh_auto_configure(1)> would use the cached value
+of B<CFLAGS> set by L<dh(1)>.
+
+This option is only available with B<< debhelper (>= 12.7~) >> when
+the package uses compatibility level 9 or later.
+
 =item B<--list>, B<-l>
 
 List all build systems supported by debhelper on this system. The list
@@ -317,17 +348,34 @@ to debhelper, to keep it clean and well-designed as needs change and its
 author gains more experience. To prevent such major changes from breaking
 existing packages, the concept of debhelper compatibility levels was 
 introduced. You must tell debhelper which compatibility level it should use, and
-it modifies its behavior in various ways.  The compatibility level is
-specified in the F<debian/compat> file and the file must be present.
-
-Tell debhelper what compatibility level to use by writing a number to
-F<debian/compat>. For example, to use v#RECOMMENDED_COMPAT# mode:
-
-  % echo #RECOMMENDED_COMPAT# > debian/compat
-
-Your package will also need a versioned build dependency on a version of
-debhelper equal to (or greater than) the compatibility level your package
-uses. So for compatibility level #RECOMMENDED_COMPAT#, ensure debian/control has:
+it modifies its behavior in various ways.
+
+In current debhelper, you can specify the compatibility level in
+F<debian/control> by adding a Build-Depends on the debhelper-compat package.
+For example, to use v#RECOMMENDED_COMPAT# mode, ensure F<debian/control> has:
+
+  Build-Depends: debhelper-compat (= #RECOMMENDED_COMPAT#)
+
+This also serves as an appropriate versioned build dependency on a sufficient
+version of the debhelper package, so you do not need to specify a separate
+versioned build dependency on the debhelper package unless you need a specific
+point release of debhelper (such as for the introduction of a new feature or
+bugfix within a compatibility level).
+
+Note that debhelper does not provide debhelper-compat for experimental or beta
+compatibility levels; packages experimenting with those compatibility levels
+should use F<debian/compat> or B<DH_COMPAT>.
+
+Prior versions of debhelper required specifying the compatibility level in the
+file F<debian/compat>, and current debhelper still supports this for backward
+compatibility, though a package may not specify a compatibility level via
+multiple methods at once. To use this method, F<debian/compat> should contain
+the compatibility level as a single number, and no other content. If you
+specify the compatibility level by this method, your package will also need a
+versioned build dependency on a version of the debhelper package equal to (or
+greater than) the compatibility level your package uses. So, if you specify
+compatibility level #RECOMMENDED_COMPAT# in F<debian/compat>, ensure
+F<debian/control> has:
 
   Build-Depends: debhelper (>= #RECOMMENDED_COMPAT#~)
 
@@ -524,13 +572,6 @@ breaks binNMUs.
 
 =item -
 
-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.
-
-=item -
-
 B<dh_installdeb> no longer installs a maintainer-provided
 debian/I<package>.shlibs file.  This is now done by B<dh_makeshlibs>
 instead.
@@ -552,6 +593,9 @@ 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
@@ -616,11 +660,30 @@ 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 v11
 
-This is the recommended mode of operation.
+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:
 
@@ -654,8 +717,8 @@ 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
+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 -
@@ -766,7 +829,7 @@ This change may cause the tools to process more files than previously.
 
 =item v12
 
-This compatibility level is still open for development; use with caution.
+This is the recommended mode of operation.
 
 Changes from v11 are:
 
@@ -869,6 +932,76 @@ F<conffiles> file.  The file has mostly been obsolete since
 compatibility level 3, where B<dh_installdeb> began to automatically
 compute the resulting F<conffiles> control file.
 
+=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 v13
+
+This compatibility level is still open for development; use with caution.
+
+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>.
+
 =back
 
 =back
@@ -1034,7 +1167,8 @@ Ignored if DH_VERBOSE is also set.
 =item B<DH_COMPAT>
 
 Temporarily specifies what compatibility level debhelper should run at,
-overriding any value in F<debian/compat>.
+overriding any value specified via Build-Depends on debhelper-compat or via the
+F<debian/compat> file.
 
 =item B<DH_NO_ACT>
 
@@ -1076,6 +1210,15 @@ that require a debhelper addon to be run during multiple builds without
 having to patch a large number of rules file. If at all possible, this should
 be avoided in favor of a --with flag in the rules file.
 
+=item B<CFLAGS>, B<CPPFLAGS>, B<CXXFLAGS>, B<OBJCFLAGS>, B<OBJCXXFLAGS>, B<GCJFLAGS>, B<FFLAGS>, B<FCFLAGS>, B<LDFLAGS>
+
+By default (in any non-deprecated compat level), debhelper will automatically
+set these flags by using L<dpkg-buildflags(1)>, when they are unset.  If you
+need to change the default flags, please use the features from
+L<dpkg-buildflags(1)> to do this (e.g. B<DEB_BUILD_MAINT_OPTIONS=hardening=all>
+or B<DEB_CPPFLAGS_MAINT_APPEND=-DCUSTOM_MACRO=true>) rather than setting the
+concrete variable directly.
+
 =back
 
 =head1 SEE ALSO