summaryrefslogtreecommitdiffstats
path: root/debhelper-compat-upgrade-checklist.pod
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-27 21:06:40 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-27 21:06:40 +0000
commitd827c6cf1631209f5042a9d1d8a7ecc24223c8a0 (patch)
tree91a431d301efd0e524bdfb0c46e97d591a9d7b03 /debhelper-compat-upgrade-checklist.pod
parentInitial commit. (diff)
downloaddebhelper-d827c6cf1631209f5042a9d1d8a7ecc24223c8a0.tar.xz
debhelper-d827c6cf1631209f5042a9d1d8a7ecc24223c8a0.zip
Adding upstream version 13.11.4.upstream/13.11.4upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r--debhelper-compat-upgrade-checklist.pod775
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