Adding upstream version 13.15.3.upstream/13.15.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 959 insertions, 0 deletions

diff --git a/debhelper.pod b/debhelper.pod
new file mode 100644
index 0000000..e8a80fa
--- /dev/null
+++ b/debhelper.pod
@@ -0,0 +1,959 @@
+=encoding UTF-8
+
+=head1 NAME
+
+debhelper - the debhelper tool suite
+
+=head1 SYNOPSIS
+
+B<dh_>I<*> [B<-v>] [B<-a>] [B<-i>] [B<--no-act>] [B<-p>I<package>] [B<-N>I<package>] [B<-P>I<tmpdir>]
+
+=head1 DESCRIPTION
+
+Debhelper is used to help you build a Debian package. The philosophy behind
+debhelper is to provide a collection of small, simple, and easily
+understood tools that are used in F<debian/rules> to automate various common
+aspects of building a package. This means less work for you, the packager.
+It also, to some degree means that these tools can be changed if Debian
+policy changes, and packages that use them will require only a rebuild to
+comply with the new policy.
+
+A typical F<debian/rules> file that uses debhelper will call several debhelper
+commands in sequence, or use L<dh(1)> to automate this process. Examples of
+rules files that use debhelper are in F</usr/share/doc/debhelper/examples/>
+
+To create a new Debian package using debhelper, you can just copy one of
+the sample rules files and edit it by hand. Or you can try the B<dh-make>
+package, which contains a L<dh_make|dh_make(1)> command that partially
+automates the process. For a more gentle introduction, the B<maint-guide> Debian 
+package contains a tutorial about making your first package using debhelper.
+
+Except where the tool explicitly denotes otherwise, all of the debhelper
+tools assume that they run from the root directory of an unpacked source
+package.  This is so they can locate find files like F<debian/control>
+when needed.
+
+=head1 DEBHELPER COMMANDS
+
+Here is the list of debhelper commands you can use. See their man
+pages for additional documentation.
+
+=over 4
+
+#LIST#
+
+=back
+
+=head2 Deprecated Commands
+
+A few debhelper commands are deprecated and should not be used.
+
+=over 4
+
+#LIST_DEPRECATED#
+
+=back
+
+=head2 Other Commands
+
+If a program's name starts with B<dh_>, and the program is not on the above
+lists, then it is not part of the debhelper package, but it should still
+work like the other programs described on this page.
+
+=head1 DEBHELPER CONFIG FILES
+
+Many debhelper commands make use of files in F<debian/> to control what they
+do. Besides the common F<debian/changelog> and F<debian/control>, which are
+in all packages, not just those using debhelper, some additional files can
+be used to configure the behavior of specific debhelper commands. These
+files are typically named debian/I<package>.foo (where I<package> of course,
+is replaced with the package that is being acted on).
+
+For example, B<dh_installdocs> uses files named F<debian/package.docs> to list
+the documentation files it will install. See the man pages of individual
+commands for details about the names and formats of the files they use.
+Generally, these files will list files to act on, one file per line. Some
+programs in debhelper use pairs of files and destinations or slightly more
+complicated formats.
+
+Note if there is only one binary package listed in F<debian/control>, then
+debhelper will use F<debian/foo> when there's no F<debian/I<package>.foo> file.
+In compat levels before compat 15, this fallback also occurs for the first
+binary package listed in F<debian/control> when there are multiple binary
+packages. However, it is often a good idea to keep the F<I<package>.> prefix
+as it is more explicit and also required when upgrading to compat 15.
+
+Additionally, there are some special cases where debhelper will always
+fallback to a prefix-less version.  These are cases such as F<debian/copyright>
+and F<debian/changelog>, where the files are generally used and needed for all
+binary packages.
+
+In some rare cases, you may want to have different versions of these files
+for different architectures or OSes. If files named debian/I<package>.foo.I<ARCH>
+or debian/I<package>.foo.I<OS> exist, where I<ARCH> and I<OS> are the same as the
+output of "B<dpkg-architecture -qDEB_HOST_ARCH>" /
+"B<dpkg-architecture -qDEB_HOST_ARCH_OS>",
+then they will be used in preference to other, more general files.
+
+Mostly, these config files are used to specify lists of various types of
+files. Documentation or example files to install, files to move, and so on.
+When appropriate, in cases like these, you can use standard shell wildcard
+characters (B<?> and B<*> and B<[>I<..>B<]> character classes) in the files.
+You can also put comments in these files; lines beginning with B<#> are
+ignored.
+
+The syntax of these files is intentionally kept very simple to make them
+easy to read, understand, and modify.
+
+=head2 Substitutions in debhelper config files
+
+In compatibility level 13 and later, it is possible to use simple
+substitutions in debhelper config files for the following tools:
+
+=over 4
+
+=item *
+
+dh_clean
+
+=item *
+
+dh_install
+
+=item *
+
+dh_installcatalogs
+
+=item *
+
+dh_installdeb
+
+=item *
+
+dh_installdirs
+
+=item *
+
+dh_installdocs
+
+=item *
+
+dh_installexamples
+
+=item *
+
+dh_installinfo
+
+=item *
+
+dh_installman
+
+=item *
+
+dh_installwm
+
+=item *
+
+dh_link
+
+=item *
+
+dh_missing
+
+=item *
+
+dh_ucf
+
+=back
+
+All substitution variables are of the form I<${foo}> and the braces
+are mandatory.  Variable names are case-sensitive and consist of
+alphanumerics (a-zA-Z0-9), hyphens (-), underscores (_), and colons (:).
+The first character must be an alphanumeric.
+
+If you need a literal dollar sign that cannot trigger a substitution,
+you can either use the B<${Dollar}> substitution or the sequence B<${}>.
+
+The following expansions are available:
+
+=over 4
+
+=item B<DEB_HOST_*>, B<DEB_BUILD_*>, B<DEB_TARGET_*>
+
+Expands to the relevant L<dpkg-architecture(1)> value (similar to
+I<dpkg-architecture -qVARIABLE_HERE>).
+
+When in doubt, the B<DEB_HOST_*> variant is the one that will work both
+for native and cross builds.
+
+For performance reasons, debhelper will attempt to resolve these
+names from the environment first before consulting
+L<dpkg-architecture(1)>.  This is mostly mentioned for completeness
+as it will not matter for most cases.
+
+=item B<Dollar>
+
+Expands to a single literal B<$>-symbol.  This symbol will I<never>
+be considered part of a substitution variable.  That is:
+
+   # Triggers an error
+   ${NO_SUCH_TOKEN}
+   # Expands to the literal value "${NO_SUCH_TOKEN}"
+   ${Dollar}{NO_SUCH_TOKEN}
+
+This variable equivalent to the sequence B<${}> and the two can be
+used interchangeably.
+
+=item B<Newline>, B<Space>, B<Tab>
+
+Expands to a single ASCII newline, space and tab respectively.
+
+This can be useful if you need to include a literal whitespace
+character (e.g. space) where it would otherwise be stripped or
+used as a separator.
+
+=item B<< env:I<NAME> >>
+
+Expands to the environment variable I<NAME>.  The environment
+variable must be set (but can be set to the empty string).
+
+=back
+
+Note that all variables must expand to a defined value.  As an example,
+if debhelper sees I<${env:FOO}>, then it will insist that the environment
+variable I<FOO> is set (it can be set to the empty string).
+
+=head3 Substitution limits
+
+To avoid infinite loops and resource exhaustion, debhelper will stop
+with an error if the text contains many substitution variables (50) or
+they expand beyond a certain size (4096 characters or 3x length of
+the original input - whichever is bigger).
+
+=head3 Substitution limitations: filtering
+
+The built-in substitution cannot be used to "filter" out content. Attempts
+to create "comments" or "empty lines" via substitution will result in those
+variables being considered a token in its own right with the content given.
+
+If you want filtering, consider using an executable debhelper config file
+with B<dh-exec> as interpreter. The B<dh-exec> tool supports several
+features out of the box. Though keep in mind that B<dh-exec> has its own
+substitution logic that can feature interact with the one from debhelper.
+
+=head2 Executable debhelper config files
+
+If you need additional flexibility, many of the debhelper tools
+(e.g. L<dh_install(1)>) support executing a config file as a script.
+
+To use this feature, simply mark the config file as executable
+(e.g. B<< chmod +x debian/I<package>.install >>) and the tool will
+attempt to execute it and use the output of the script.  In many
+cases, you can use L<dh-exec(1)> as interpreter of the config file to
+retain most of the original syntax while getting the additional
+flexibility you need.
+
+
+When using executable debhelper config files, please be aware of the
+following:
+
+=over 4
+
+=item *
+
+The executable config file B<must> exit with success (i.e. its return
+code should indicate success).
+
+=item *
+
+In compatibility level 13+, the output will be subject to substitutions
+(see L</Substitutions in debhelper config files>) where the tool
+support these.  Remember to be careful if your generator I<also> provides
+substitutions as this can cause unnecessary confusion. Notably, the
+commonly used B<dh-exec> tool has its own substitution support.
+
+Otherwise, the output will be used exactly as-is.  Notably, debhelper
+will I<not> expand wildcards or strip comments or strip whitespace
+in the output it reads. The B<dh-exec> tool has an output filter on
+by default that will prune these things out.
+
+=back
+
+If you need the package to build on a file system where you cannot
+disable the executable bit, then you can use L<dh-exec(1)> and its
+B<strip-output> script.
+
+=head1 SHARED DEBHELPER OPTIONS
+
+The following command line options are supported by all debhelper programs.
+
+=over 4
+
+=item B<-v>, B<--verbose>
+
+Verbose mode: show commands that modify the package build directory.
+
+Note that verbose mode may also output other "internal" commands that do not
+directly affect the package build directory.
+
+=item B<--no-act>
+
+Do not really do anything. If used with -v, the result is that the command
+will output what it would have done.
+
+=item B<-a>, B<--arch>
+
+Act on architecture dependent packages that should be built for the
+B<DEB_HOST_ARCH> architecture.
+
+=item B<-i>, B<--indep>
+
+Act on all architecture independent packages.
+
+=item B<-p>I<package>, B<--package=>I<package>
+
+Act on the package named I<package>. This option may be specified multiple
+times to make debhelper operate on a given set of packages.
+
+=item B<-s>, B<--same-arch>
+
+Deprecated alias of B<-a>.
+
+This option is removed in compat 12.
+
+=item B<-N>I<package>, B<--no-package=>I<package>
+
+Do not act on the specified package even if an B<-a>, B<-i>, or B<-p> option lists
+the package as one that should be acted on.
+
+=item B<--remaining-packages>
+
+Do not act on the packages which have already been acted on by this debhelper
+command earlier (i.e. if the command is present in the package debhelper log).
+For example, if you need to call the command with special options only for a
+couple of binary packages, pass this option to the last call of the command to
+process the rest of packages with default settings. 
+
+=item B<-P>I<tmpdir>, B<--tmpdir=>I<tmpdir>
+
+Use I<tmpdir> for package build directory. The default is debian/I<package>
+
+=item B<--mainpackage=>I<package>
+
+B<Deprecated>: This option has no practical use in compat 15 or later as the
+behaviour it affects is removed in compat 15.
+
+This little-used option changes the package which debhelper considers the
+"main package", that is, the first one listed in F<debian/control>, and the
+one for which F<debian/foo> files can be used instead of the usual
+F<debian/package.foo> files.
+
+=item B<-O=>I<option>|I<bundle>
+
+This is used by L<dh(1)> when passing user-specified options to all the
+commands it runs. If the command supports the specified option or option
+bundle, it will take effect. If the command does not support the option (or
+any part of an option bundle), it will be ignored.
+
+=back
+
+=head1 COMMON DEBHELPER OPTIONS
+
+The following command line options are supported by some debhelper programs.
+See the man page of each program for a complete explanation of what each
+option does.
+
+=over 4
+
+=item B<-n>
+
+Do not modify F<postinst>, F<postrm>, etc. scripts.
+
+=item B<-X>I<item>, B<--exclude=>I<item>
+
+Exclude an item from processing. This option may be used multiple times,
+to exclude more than one thing. The I<item> is typically part of a
+filename, and any file containing the specified text will be excluded.
+
+=item B<-A>, B<--all>
+
+Makes files or other items that are specified on the command line take effect
+in ALL packages acted on, not just the first.
+
+=back
+
+=head1 BUILD SYSTEM OPTIONS
+
+The following command line options are supported by all of the B<dh_auto_>I<*>
+debhelper programs. These programs support a variety of build systems,
+and normally heuristically determine which to use, and how to use them.
+You can use these command line options to override the default behavior.
+Typically these are passed to L<dh(1)>, which then passes them to all the 
+B<dh_auto_>I<*> programs.
+
+=over 4
+
+=item B<-S>I<buildsystem>, B<--buildsystem=>I<buildsystem>
+
+Force use of the specified I<buildsystem>, instead of trying to auto-select
+one which might be applicable for the package.
+
+Pass B<none> as I<buildsystem> to disable auto-selection.
+
+=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.
+
+B<Warning>: The B<--sourcedir> variant matches a similar named option in
+B<dh_install> and B<dh_missing> (etc.) for historical reasons.  While they
+have a similar name, they have very distinct purposes and in some cases
+it can cause errors when this variant is passed to B<dh> (when then passes
+it on to all tools).
+
+=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
+will be chosen.
+
+If this option is not specified, building will be done in source by default
+unless the build system requires or prefers out of source tree building.
+In such a case, the default build directory will be used even if
+B<--builddirectory> is not specified.
+
+If the build system prefers out of source tree building but still
+allows in source building, the latter can be re-enabled by passing a build
+directory path that is the same as the source directory path.
+
+=item B<--parallel>, B<--no-parallel>
+
+Control whether parallel builds should be used if underlying build
+system supports them.  The number of parallel jobs is controlled by
+the B<DEB_BUILD_OPTIONS> environment variable (L<Debian Policy,
+section 4.9.1>) at build time. It might also be subject to a build
+system specific limit.
+
+If neither option is specified, debhelper currently defaults to
+B<--parallel> in compat 10 (or later) and B<--no-parallel> otherwise.
+
+As an optimization, B<dh> will try to avoid passing these options to
+subprocesses, if they are unnecessary and the only options passed.
+Notably this happens when B<DEB_BUILD_OPTIONS> does not have a
+I<parallel> parameter (or its value is 1).
+
+=item B<--max-parallel=>I<maximum>
+
+This option implies B<--parallel> and allows further limiting the number of
+jobs that can be used in a parallel build. If the package build is known to
+only work with certain levels of concurrency, you can set this to the maximum
+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 variables (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
+includes both default and third party build systems (marked as such). Also
+shows which build system would be automatically selected, or which one
+is manually specified with the B<--buildsystem> option.
+
+=back
+
+=head1 COMPATIBILITY LEVELS
+
+From time to time, major non-backwards-compatible changes need to be made
+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.
+
+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 put the compat level in the B<X-DH-Compat> field of the source stanza
+of the F<debian/control> file (or, if only for selected commands, the
+B<DH_COMPAT> environment variable).
+
+Historically, debhelper required specifying the compatibility level in the
+file F<debian/compat>, and debhelper up to version 14 supports this for backward
+compatibility. To use this method, the F<debian/compat> file 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#~)
+
+Note that you must use exactly one method for specifying the default debhelper
+compat level of the package. Whenever possible, the debhelper-compat
+build-dependency is recommended.
+
+If needed be, the B<DH_COMPAT> environment variable can be used to override
+the compat level for a given command.  The feature is mostly useful for
+either temporarily upgrading a few commands to a new compat level or
+keeping a few commands on a lower compat level.  The feature is best used
+sparingly as it effectively introduces special-cases into the
+F<debian/rules> file that may be surprising to maintainers or reviewers
+(or, in the long term, to yourself).
+
+Unless otherwise indicated, all debhelper documentation assumes that you
+are using the most recent compatibility level, and in most cases does not
+indicate if the behavior is different in an earlier compatibility level, so
+if you are not using the most recent compatibility level, you're advised to
+read below for notes about what is different in earlier compatibility
+levels.
+
+=head2 Supported compatibility levels
+
+The list of supported compatibility levels and the related upgrade check
+list has moved to L<debhelper-compat-upgrade-checklist(7)>.
+
+=head1 NOTES
+
+=head2 Multiple binary package support
+
+If your source package generates more than one binary package, debhelper
+programs will default to acting on all binary packages when run. If your
+source package happens to generate one architecture dependent package, and
+another architecture independent package, this is not the correct behavior,
+because you need to generate the architecture dependent packages in the
+binary-arch F<debian/rules> target, and the architecture independent packages
+in the binary-indep F<debian/rules> target.
+
+To facilitate this, as well as give you more control over which packages
+are acted on by debhelper programs, all debhelper programs accept the
+B<-a>, B<-i>, B<-p>, and B<-s> parameters. These parameters are cumulative. 
+If none are given, debhelper programs default to acting on all packages listed
+in the control file, with the exceptions below.
+
+First, any package whose B<Architecture> field in B<debian/control> does not
+match the B<DEB_HOST_ARCH> architecture will be excluded
+(L<Debian Policy, section 5.6.8>).
+
+Also, some additional packages may be excluded based on the contents of the
+B<DEB_BUILD_PROFILES> environment variable and B<Build-Profiles> fields in
+binary package stanzas in B<debian/control>, according to the draft policy at
+L<https://wiki.debian.org/BuildProfileSpec>.
+
+=head3 Interaction between package selections and Build-Profiles
+
+Build-Profiles affect which packages are included in the package
+selections mechanisms in debhelper.  Generally, the package selections
+are described from the assumption that all packages are enabled.  This
+section describes how the selections react when a package is disabled
+due to the active Build-Profiles (or lack of active Build-Profiles).
+
+=over 4
+
+=item -a/--arch, -i/--indep OR no selection options (a raw "dh_X" call)
+
+The package disabled by Build-Profiles is silently excluded from the
+selection.
+
+Note you will receive a warning if I<all> packages related to these
+selections are disabled.  In that case, it generally does not make
+sense to do the build in the first place.
+
+=item -N I<package> / --no-package I<package>
+
+The option is accepted and effectively does nothing.
+
+=item -p I<package> / --package I<package>
+
+The option is accepted, but debhelper will not act on the package.
+
+=back
+
+Note that it does not matter whether a package is enabled or disabled
+by default.
+
+=head2 Automatic generation of Debian install scripts
+
+Some debhelper commands will automatically generate parts of Debian
+maintainer scripts. If you want these automatically generated things
+included in your existing Debian maintainer scripts, then you need to add
+B<#DEBHELPER#> to your scripts, in the place the code should be added.
+B<#DEBHELPER#> will be replaced by any auto-generated code when you run
+B<dh_installdeb>.
+
+If a script does not exist at all and debhelper needs to add something to
+it, then debhelper will create the complete script.
+
+All debhelper commands that automatically generate code in this way let it
+be disabled by the -n parameter (see above).
+
+Note that the inserted code will be shell code, so you cannot directly use
+it in a Perl script. If you would like to embed it into a Perl script, here
+is one way to do that (note that I made sure that $1, $2, etc are set with
+the set command):
+
+  my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
+  #DEBHELPER#
+  EOF
+  if (system($temp)) {
+     my $exit_code = ($? >> 8) & 0xff;
+     my $signal = $? & 0x7f;
+     if ($exit_code) {
+         die("The debhelper script failed with error code: ${exit_code}");
+     } else {
+         die("The debhelper script was killed by signal: ${signal}");
+     }
+  }
+
+=head2 Automatic generation of miscellaneous dependencies.
+
+Some debhelper commands may make the generated package need to depend on
+some other packages. For example, if you use L<dh_installdebconf(1)>, your
+package will generally need to depend on debconf. Or if you use
+L<dh_installxfonts(1)>, your package will generally need to depend on a
+particular version of xutils. Keeping track of these miscellaneous
+dependencies can be annoying since they are dependent on how debhelper does
+things, so debhelper offers a way to automate it.
+
+All commands of this type, besides documenting what dependencies may be
+needed on their man pages, will automatically generate a substvar called
+B<${misc:Depends}>. If you put that token into your F<debian/control> file, it
+will be expanded to the dependencies debhelper figures you need. 
+
+This is entirely independent of the standard B<${shlibs:Depends}> generated by
+L<dh_makeshlibs(1)>, and the B<${perl:Depends}> generated by L<dh_perl(1)>.
+You can choose not to use any of these, if debhelper's guesses don't match
+reality.
+
+=head2 Package build directories
+
+By default, all debhelper programs assume that the temporary directory used
+for assembling the tree of files in a package is debian/I<package>.
+
+Sometimes, you might want to use some other temporary directory. This is
+supported by the B<-P> flag. For example, "B<dh_installdocs -Pdebian/tmp>", will
+use B<debian/tmp> as the temporary directory. Note that if you use B<-P>, the 
+debhelper programs can only be acting on a single package at a time. So if 
+you have a package that builds many binary packages, you will need to also 
+use the B<-p> flag to specify which binary package the debhelper program will
+act on.
+
+=head2 udebs
+
+Debhelper includes support for udebs. To create a udeb with debhelper,
+add "B<Package-Type: udeb>" to the package's stanza in F<debian/control>.
+Debhelper will try to create udebs that comply with debian-installer
+policy, by making the generated package files end in F<.udeb>, not
+installing any documentation into a udeb, skipping over
+F<preinst>, F<postrm>, F<prerm>, and F<config> scripts, etc.
+
+=head1 ENVIRONMENT
+
+This section describes some of the environment variables that influences
+the behaviour of debhelper or which debhelper interacts with.
+
+It is important to note that these must be actual environment variables in
+order to affect the behaviour of debhelper (not simply F<Makefile> variables).
+To specify them properly in F<debian/rules>, be sure to "B<export>" them. For
+example, "B<export DH_VERBOSE>".
+
+=over 4
+
+=item B<DH_VERBOSE>
+
+Set to a non-empty value to enable verbose mode.  Please see the B<-v> / B<--verbose>
+option for details.
+
+=item B<DH_QUIET>
+
+Set to a non-empty value to enable quiet mode. Debhelper will not output commands calling
+the upstream build system nor will dh print which subcommands are called
+and depending on the upstream build system might make that more quiet, too.
+This makes it easier to spot important messages but makes the output quite
+useless as buildd log.
+
+Ignored if DH_VERBOSE is also set or B<-v> / B<--verbose> is passed.
+
+=item B<DH_COMPAT>
+
+Temporarily specifies what compatibility level debhelper should run at,
+overriding the default compat level of the source package.
+
+=item B<DH_NO_ACT>
+
+Set to B<1> to enable no-act mode.
+
+=item B<DH_OPTIONS>
+
+All debhelper tools will parse command line arguments listed in this variable
+before any command option (as if they had been prepended to the command
+line arguments).  Unfortunately, some third-party provided tools may not
+support this variable and will ignore these command line arguments.
+
+When using L<dh(1)>, it can be passed options that will be passed on to each
+debhelper command, which is generally better than using DH_OPTIONS.
+
+=item B<DH_ALWAYS_EXCLUDE>
+
+If set, this adds the value the variable is set to to the B<-X> options of all
+commands that support the B<-X> option. Moreover, B<dh_builddeb> will B<rm -rf>
+anything that matches the value in your package build tree.
+
+This can be useful if you are doing a build from a CVS source tree, in
+which case setting B<DH_ALWAYS_EXCLUDE=CVS> will prevent any CVS directories
+from sneaking into the package you build. Or, if a package has a source
+tarball that (unwisely) includes CVS directories, you might want to export
+B<DH_ALWAYS_EXCLUDE=CVS> in F<debian/rules>, to make it take effect wherever
+your package is built.
+
+Multiple things to exclude can be separated with colons, as in
+B<DH_ALWAYS_EXCLUDE=CVS:.svn>
+
+=item B<DH_EXTRA_ADDONS>
+
+If set, this adds the specified dh addons to be run in the appropriate places
+in the sequence of commands. This is equivalent to specifying the addon to run
+with the --with flag in the debian/rules file. Any --without calls specifying
+an addon in this environment variable will not be run.
+
+This is intended to be used by downstreams or specific local configurations
+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<DH_COLORS>, B<DPKG_COLORS>
+
+These variables can be used to control whether debhelper commands should use
+colors in their textual output.  Can be set to "always", "auto" (the default),
+or "never".
+
+Note that B<DPKG_COLOR> also affects a number of dpkg related tools and
+debhelper uses it on the assumption that you want the same color setting for
+dpkg and debhelper.  In the off-hand chance you want different color setting
+for debhelper, you can use B<DH_COLORS> instead or in addition to
+B<DPKG_COLORS>.
+
+=item B<NO_COLOR>
+
+If no explicit request for color has been given (e.g. B<DH_COLORS> and
+B<DPKG_COLORS> are both unset), the presence of this environment variable
+cause the default color setting to be "never".
+
+The variable is defined according to L<https://no-color.org/>.  In this
+project, the environment variables (such as B<DH_COLORS>) are considered
+an explicit request for color.
+
+=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.
+
+=item B<HOME>, B<XDG_*>
+
+In compat 13 and later, these environment variables are reset before invoking
+the upstream build system via the B<dh_auto_*> helpers.  The variables B<HOME>
+(all B<dh_auto_*> helpers) and B<XDG_RUNTIME_DIR> (B<dh_auto_test> only) will
+be set to a writable directory. All remaining variables and B<XDG_RUNTIME_DIR>
+(except for during B<dh_auto_test>) will be cleared.
+
+The B<HOME> directory will be created as an empty directory but it will be
+reused between calls to B<dh_auto_*>.  Any content will persist until
+explicitly deleted or B<dh_clean>.
+
+=item B<DEB_BUILD_OPTIONS>
+
+Please see L</Supported flags in DEB_BUILD_OPTIONS> for this environment
+variable.
+
+Please note that this variable should I<not> be altered by package maintainers
+inside F<debian/rules> to change the behaviour of debhelper.  Instead, where
+the package maintainer need these features, they should look disabling the
+relevant feature directly (e.g. by overriding the concrete tools).
+
+=item B<DEB_BUILD_MAINT_OPTIONS>
+
+This is a dpkg specific environment variable (see e.g. L<dpkg-buildflags(1)>).
+The debhelper tool suite silently ignores it.
+
+It is documented here because it has a similar name to B<DEB_BUILD_OPTIONS>,
+which make some people mistakenly assume that debhelper will also react to this
+variable.
+
+=back
+
+=head2 Supported flags in DEB_BUILD_OPTIONS
+
+The debhelper tool suite reacts to the following flags in B<DEB_BUILD_OPTIONS>.
+
+=over 4
+
+=item B<dherroron=obsolete-compat-levels>
+
+I<This is a debhelper specific value.>
+
+When B<dherroron> is present and set to B<obsolete-compat-levels>, then
+debhelper tools will promote deprecation warnings for usage of old soon
+to be removed compat levels into errors.
+
+This is useful for automated checking for code relying on deprecated
+compat levels that is scheduled for removal.
+
+This option is intended for testing purposes; not production builds.
+
+=item B<nostrip>
+
+I<This value will change the content of the debs being built.  The .deb
+packages built when this is set is therefore not bit-for-bit reproducible
+with a regular build in the general case.>
+
+This value will cause the official debhelper tools will skip actions and
+helpers that either remove, detach or deduplicate debugging symbols in
+ELF binaries.
+
+This value affects L<dh_dwz(1)> and L<dh_strip(1)>.
+
+=item B<nocheck>
+
+This value will cause the official debhelper build systems to skip runs
+of upstream test suites.
+
+Package maintainers looking to avoid running the upstream tests should
+B<not> rely on this.  Instead, they can add an empty override target
+to skip B<dh_auto_test>.
+
+This value affects L<dh_auto_test(1)>.
+
+=item B<nodoc>
+
+I<This value will change the content of the debs being built.  The .deb
+packages built when this is set is therefore not bit-for-bit reproducible
+with a regular build in the general case.>
+
+This value will cause several debhelper tools to skip installation of
+documentation such as manpages or upstream provided documentation.
+Additionally, the tools will also ignore if declared documentation is
+"missing" on the assumption that the documentation has not been built.
+
+This value effects tools I<like> L<dh_installdocs(1)>, which I<knows>
+it is working with documentation.
+
+=item B<notrimdch>
+
+I<This value will change the content of the debs being built.  The .deb
+packages built when this is set is therefore not bit-for-bit reproducible
+with a regular build in the general case.>
+
+This value will cause L<dh_installchangelogs(1)> to act as if it
+had been passed the B<--no-trim> option, forcing it to forgo removing
+older entries from changelogs.
+
+=item B<noautodbgsym>, B<noddebs>
+
+I<The official name is noautodbgsym.  The noddebs variant is accepted
+for historical reasons.>
+
+This value causes debhelper to skip the generation of automatically
+generated debug symbol packages.
+
+This value affects L<dh_strip(1)>.
+
+=item B<parallel=N>
+
+This value enables debhelper to use up to B<N> threads or processes
+(subject to parameters like B<--no-parallel> and B<--max-parallel=M>).
+Not all debhelper tools work with parallel tasks and may silently
+ignore the request.
+
+This value affects many debhelper tools.  Most notably B<dh_auto_*>,
+which will attempt to run the underlying upstream build system with
+that number of threads.
+
+=item B<terse>
+
+This value will cause the official debhelper build systems to configure
+upstream builds to be terse (i.e. reduce verbosity in their output).
+This is subject to the upstream and the debhelper build system
+supporting such features.
+
+This value affects most B<dh_auto_*> tools directly. For commands
+provided by the debhelper package, it also causes the tools to act like
+the B<DH_QUIET> environment variable was non-empty.
+
+=back
+
+Unknown flags are silently ignored.
+
+Note third-party debhelper-like tools or third-party provided build systems
+may or may not react to the above flags.  This tends to depend on
+implementation details of the tool.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<debhelper-compat-upgrade-checklist(7)>
+
+List of supported compat levels and an upgrade checklist for each of them.
+
+=item F</usr/share/doc/debhelper/examples/>
+
+A set of example F<debian/rules> files that use debhelper.
+
+=item L<http://joeyh.name/code/debhelper/>
+
+Debhelper web site.
+
+=back
+
+=head1 AUTHOR
+
+Joey Hess <joeyh@debian.org>
+
+=cut