Adding upstream version 1.20.13.upstream/1.20.13upstream

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

1 files changed, 723 insertions, 0 deletions

diff --git a/man/dpkg-buildpackage.pod b/man/dpkg-buildpackage.pod
new file mode 100644
index 0000000..e648a80
--- /dev/null
+++ b/man/dpkg-buildpackage.pod
@@ -0,0 +1,723 @@
+# dpkg manual page - dpkg-buildpackage(1)
+#
+# Copyright © 1995-1996 Ian Jackson
+# Copyright © 2000 Wichert Akkerman <wakkerma@debian.org>
+# Copyright © 2007-2008 Frank Lichtenheld <djpig@debian.org>
+# Copyright © 2008-2015 Guillem Jover <guillem@debian.org>
+# Copyright © 2008-2012 Raphaël Hertzog <hertzog@debian.org>
+#
+# This is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+=encoding utf8
+
+=head1 NAME
+
+dpkg-buildpackage - build binary or source packages from sources
+
+=head1 SYNOPSIS
+
+B<dpkg-buildpackage>
+[I<option>...]
+
+=head1 DESCRIPTION
+
+B<dpkg-buildpackage>
+is a program that automates the process of building a Debian package. It
+consists of the following steps:
+
+=over
+
+=item B<1.>
+
+It prepares the build environment by setting various environment
+variables (see B<ENVIRONMENT>), runs the B<init> hook, and calls
+B<dpkg-source --before-build> (unless B<-T> or B<--target>
+has been used).
+
+=item B<2.>
+
+It checks that the build-dependencies and build-conflicts
+are satisfied (unless B<-d> or B<--no-check-builddeps> is specified).
+
+=item B<3.>
+
+If one or more specific targets have been selected with the B<-T> or
+B<--target> option, it calls those targets and stops here. Otherwise it
+runs the B<preclean> hook and calls B<fakeroot debian/rules clean> to
+clean the build-tree (unless B<-nc> or B<--no-pre-clean>
+is specified).
+
+=item B<4.>
+
+It runs the B<source> hook and calls B<dpkg-source -b> to generate
+the source package (if a B<source> build has been requested with
+B<--build> or equivalent options).
+
+=item B<5.>
+
+It runs the B<build> hook and calls B<debian/rules> I<build-target>,
+then runs the B<binary> hook followed by B<fakeroot debian/rules>
+I<binary-target> (unless a source-only build has been requested with
+B<--build=source> or equivalent options).
+Note that I<build-target> and I<binary-target> are either B<build>
+and B<binary> (default case, or if an B<any> and B<all> build
+has been requested with B<--build> or equivalent options), or
+B<build-arch> and B<binary-arch> (if an B<any> and not B<all>
+build has been requested with B<--build> or equivalent options), or
+B<build-indep> and B<binary-indep> (if an B<all> and not B<any>
+build has been requested with B<--build> or equivalent options).
+
+=item B<6.>
+
+It runs the B<buildinfo>
+hook and calls B<dpkg-genbuildinfo> to generate a B<.buildinfo> file.
+Several B<dpkg-buildpackage> options are forwarded to
+B<dpkg-genbuildinfo>.
+
+=item B<7.>
+
+It runs the B<changes> hook and calls B<dpkg-genchanges> to
+generate a B<.changes> file.
+The name of the B<.changes> file will depend on the type of build and
+will be as specific as necessary but not more;
+for a build that includes B<any> the name will be
+I<source-name>B<_>I<binary-version>B<_>I<arch>B<.changes>,
+or otherwise for a build that includes B<all> the name will be
+I<source-name>B<_>I<binary-version>B<_>B<all.changes>,
+or otherwise for a build that includes B<source> the name will be
+I<source-name>B<_>I<source-version>B<_>B<source.changes>.
+Many B<dpkg-buildpackage> options are forwarded to
+B<dpkg-genchanges>.
+
+=item B<8.>
+
+It runs the B<postclean> hook and if B<-tc> or B<--post-clean>
+is specified, it will call B<fakeroot debian/rules clean> again.
+
+=item B<9.>
+
+It calls B<dpkg-source --after-build>.
+
+=item B<10.>
+
+It runs the B<check> hook and calls a package checker for the
+B<.changes> file (if a command is specified in B<DEB_CHECK_COMMAND> or
+with B<--check-command>).
+
+=item B<11.>
+
+It runs the B<sign> hook and calls B<gpg> (as long as it
+is not an UNRELEASED build, or B<--no-sign> is specified) to sign the
+B<.dsc> file (if any, unless
+B<-us> or B<--unsigned-source> is specified), the B<.buildinfo>
+file (unless B<-ui>, B<--unsigned-buildinfo>,
+B<-uc> or B<--unsigned-changes> is specified) and
+the B<.changes> file (unless B<-uc> or B<--unsigned-changes>
+is specified).
+
+=item B<12.>
+
+It runs the B<done> hook.
+
+=back
+
+=head1 OPTIONS
+
+All long options can be specified both on the command line and in the
+B<dpkg-buildpackage> system and user configuration files.
+Each line in the configuration file is either an option (exactly the same
+as the command line option but without leading hyphens) or a comment (if
+it starts with a ‘B<#>’).
+
+=over
+
+=item B<--build=>I<type>
+
+Specifies the build I<type> from a comma-separated list of components
+(since dpkg 1.18.5).
+Passed to B<dpkg-genchanges>.
+
+The allowed values are:
+
+=over
+
+=item B<source>
+
+Builds the source package.
+
+B<Note:> When using this value standalone and if what you want is simply to
+(re-)build the source package from a clean source tree, using
+B<dpkg-source> directly is always a better option as it does not
+require any build dependencies to be installed which are otherwise
+needed to be able to call the B<clean> target.
+
+=item B<any>
+
+Builds the architecture specific binary packages.
+
+=item B<all>
+
+Builds the architecture independent binary packages.
+
+=item B<binary>
+
+Builds the architecture specific and independent binary packages.
+This is an alias for B<any,all>.
+
+=item B<full>
+
+Builds everything.
+This is an alias for B<source,any,all>, and the same as the default
+case when no build option is specified.
+
+=back
+
+=item B<-g>
+
+Equivalent to B<--build=source,all> (since dpkg 1.17.11).
+
+=item B<-G>
+
+Equivalent to B<--build=source,any> (since dpkg 1.17.11).
+
+=item B<-b>
+
+Equivalent to B<--build=binary> or B<--build=any,all>.
+
+=item B<-B>
+
+Equivalent to B<--build=any>.
+
+=item B<-A>
+
+Equivalent to B<--build=all>.
+
+=item B<-S>
+
+Equivalent to B<--build=source>.
+
+=item B<-F>
+
+Equivalent to B<--build=full>, B<--build=source,binary> or
+B<--build=source,any,all> (since dpkg 1.15.8).
+
+=item B<--target=>I<target>[,...]
+
+=item B<--target> I<target>[,...]
+
+=item B<-T>, B<--rules-target=>I<target>[,...]
+
+Calls B<debian/rules> I<target> once per target specified, after
+having setup the build environment (except for calling
+B<dpkg-source --before-build>), and stops the package build process
+here (since dpkg 1.15.0, long option since dpkg 1.18.8, multi-target
+support since dpkg 1.18.16).
+If B<--as-root> is also given, then the command is executed
+as root (see B<--root-command>).
+Note that known targets that are required to
+be run as root do not need this option (i.e. the B<clean>, B<binary>,
+B<binary-arch> and B<binary-indep> targets).
+
+=item B<--as-root>
+
+Only meaningful together with B<--target> (since dpkg 1.15.0).
+Requires that the target be run with root rights.
+
+=item B<-si>
+
+=item B<-sa>
+
+=item B<-sd>
+
+=item B<-v>I<version>
+
+=item B<-C>I<changes-description>
+
+=item B<-m>, B<--release-by=>I<maintainer-address>
+
+=item B<-e>, B<--build-by=>I<maintainer-address>
+
+Passed unchanged to B<dpkg-genchanges>. See its manual page.
+
+=item B<-a>, B<--host-arch> I<architecture>
+
+Specify the Debian architecture we build for (long option since dpkg 1.17.17).
+The architecture of the
+machine we build on is determined automatically, and is also the default
+for the host machine.
+
+=item B<-t>, B<--host-type> I<gnu-system-type>
+
+Specify the GNU system type we build for (long option since dpkg 1.17.17).
+It can be used in place
+of B<--host-arch> or as a complement to override the default GNU system type
+of the host Debian architecture.
+
+=item B<--target-arch> I<architecture>
+
+Specify the Debian architecture the binaries built will build for
+(since dpkg 1.17.17).
+The default value is the host machine.
+
+=item B<--target-type> I<gnu-system-type>
+
+Specify the GNU system type the binaries built will build for
+(since dpkg 1.17.17).
+It can be
+used in place of B<--target-arch> or as a complement to override the
+default GNU system type of the target Debian architecture.
+
+=item B<-P>, B<--build-profiles=>I<profile>[B<,>...]
+
+Specify the profile(s) we build, as a comma-separated list (since dpkg 1.17.2,
+long option since dpkg 1.18.8).
+The default
+behavior is to build for no specific profile. Also sets them (as a space
+separated list) as the B<DEB_BUILD_PROFILES> environment variable which
+allows, for example, B<debian/rules> files to use this information for
+conditional builds.
+
+=item B<-j>, B<--jobs>[=I<jobs>|B<auto>]
+
+Number of jobs allowed to be run simultaneously, number of jobs matching
+the number of online processors if B<auto> is specified
+(since dpkg 1.17.10), or unlimited number if I<jobs> is not specified,
+equivalent to the
+B<make>(1)
+option of the same name (since dpkg 1.14.7, long option since dpkg 1.18.8).
+Will add itself to the B<MAKEFLAGS>
+environment variable, which should cause all subsequent make
+invocations to inherit the option, thus forcing the parallel setting on
+the packaging (and possibly the upstream build system if that uses make)
+regardless of their support for parallel builds, which might cause build
+failures.
+Also adds B<parallel=>I<jobs> or
+B<parallel> to the B<DEB_BUILD_OPTIONS> environment variable which
+allows debian/rules files to use this information for their own purposes.
+The B<-j> value will override the B<parallel=>I<jobs> or
+B<parallel> option in the B<DEB_BUILD_OPTIONS> environment variable.
+Note that the B<auto> value will get replaced by the actual number of
+currently active processors, and as such will not get propagated to any
+child process. If the number of online processors cannot be inferred then
+the code will fallback to using serial execution (since dpkg 1.18.15),
+although this should only happen on exotic and unsupported systems.
+
+=item B<-J>, B<--jobs-try>[=I<jobs>|B<auto>]
+
+This option (since dpkg 1.18.2, long option since dpkg 1.18.8) is equivalent
+to the B<-j> option except that it does not set the B<MAKEFLAGS>
+environment variable, and as such it is safer to use with any package
+including those that are not parallel-build safe.
+
+B<auto> is the default behavior (since dpkg 1.18.11). Setting the number
+of jobs to 1 will restore a serial behavior.
+
+=item B<-D>, B<--check-builddeps>
+
+Check build dependencies and conflicts; abort if unsatisfied (long option
+since dpkg 1.18.8).
+This is the default behavior.
+
+=item B<-d>, B<--no-check-builddeps>
+
+Do not check build dependencies and conflicts (long option since dpkg 1.18.8).
+
+=item B<--ignore-builtin-builddeps>
+
+Do not check built-in build dependencies and conflicts (since dpkg 1.18.2).
+These are the distribution specific implicit build dependencies usually
+required in a build environment, the so called Build-Essential package set.
+
+=item B<--rules-requires-root>
+
+Do not honor the B<Rules-Requires-Root> field, falling back to its
+legacy default value (since dpkg 1.19.1).
+
+=item B<-nc>, B<--no-pre-clean>
+
+Do not clean the source tree before building (long option since dpkg 1.18.8).
+Implies B<-b> if nothing else has been selected among B<-F>,
+B<-g>, B<-G>, B<-B>, B<-A> or B<-S>.
+Implies B<-d> with B<-S> (since dpkg 1.18.0).
+
+=item B<--pre-clean>
+
+Clean the source tree before building (since dpkg 1.18.8).
+This is the default behavior.
+
+=item B<-tc>, B<--post-clean>
+
+Clean the source tree (using
+I<gain-root-command>
+B<debian/rules clean>)
+after the package has been built (long option since dpkg 1.18.8).
+
+=item B<--no-post-clean>
+
+Do not clean the source tree after the package has been built
+(since dpkg 1.19.1).
+This is the default behavior.
+
+=item B<--sanitize-env>
+
+Sanitize the build environment (since dpkg 1.20.0).
+This will reset or remove environment variables, umask, and any other process
+attributes that might otherwise adversely affect the build of packages.
+Because the official entry point to build packages is B<debian/rules>,
+packages cannot rely on these settings being in place, and thus should work
+even when they are not.
+What to sanitize is vendor specific.
+
+=item B<-r>, B<--root-command=>I<gain-root-command>
+
+When
+B<dpkg-buildpackage>
+needs to execute part of the build process as root, it prefixes the
+command it executes with
+I<gain-root-command>
+if one has been specified (long option since dpkg 1.18.8).
+Otherwise, if none has been specified,
+B<fakeroot> will be used by default, if the command is present.
+I<gain-root-command>
+should start with the name of a program on the
+B<PATH>
+and will get as arguments the name of the real command to run and the
+arguments it should take.
+I<gain-root-command>
+can include parameters (they must be space-separated) but no shell
+metacharacters.
+I<gain-root-command>
+might typically be
+B<fakeroot>, B<sudo>, B<super> or B<really>.
+B<su>
+is not suitable, since it can only invoke the user's shell with
+B<-c>
+instead of passing arguments individually to the command to be run.
+
+=item B<-R>, B<--rules-file=>I<rules-file>
+
+Building a Debian package usually involves invoking
+B<debian/rules>
+as a command with several standard parameters (since dpkg 1.14.17,
+long option since dpkg 1.18.8).
+With this option it's
+possible to use another program invocation to build the package (it can
+include space separated parameters).
+Alternatively it can be used to execute the standard rules file with
+another make program (for example by using
+B</usr/local/bin/make -f debian/rules>
+as I<rules-file>).
+
+=item B<--check-command=>I<check-command>
+
+Command used to check the B<.changes> file itself and any artifact built
+referenced in the file (since dpkg 1.17.6).
+The command should take the B<.changes> pathname
+as an argument. This command will usually be B<lintian>.
+
+=item B<--check-option=>I<opt>
+
+Pass option I<opt> to the I<check-command> specified with
+B<DEB_CHECK_COMMAND> or B<--check-command> (since dpkg 1.17.6).
+Can be used multiple times.
+
+=item B<--hook->I<hook-name>B<=>I<hook-command>
+
+Set the specified shell code I<hook-command> as the hook I<hook-name>,
+which will run at the times specified in the run steps (since dpkg 1.17.6).
+The hooks will
+always be executed even if the following action is not performed (except
+for the B<binary> hook).
+All the hooks will run in the unpacked source directory.
+
+B<Note:> Hooks can affect the build process, and cause build failures if
+their commands fail, so watch out for unintended consequences.
+
+The current I<hook-name> supported are:
+
+B<init preclean source build binary buildinfo changes postclean check sign done>
+
+The I<hook-command> supports the following substitution format string,
+which will get applied to it before execution:
+
+=over
+
+=item B<%%>
+
+A single % character.
+
+=item B<%a>
+
+A boolean value (0 or 1), representing whether the following action is
+being performed.
+
+=item B<%p>
+
+The source package name.
+
+=item B<%v>
+
+The source package version.
+
+=item B<%s>
+
+The source package version (without the epoch).
+
+=item B<%u>
+
+The upstream version.
+
+=back
+
+=item B<--buildinfo-option=>I<opt>
+
+Pass option I<opt> to B<dpkg-genbuildinfo> (since dpkg 1.18.11).
+Can be used multiple times.
+
+=item B<-p>, B<--sign-command=>I<sign-command>
+
+When B<dpkg-buildpackage> needs to execute GPG to sign a source
+control (B<.dsc>) file or a B<.changes> file it will run
+I<sign-command> (searching the B<PATH> if necessary) instead of
+B<gpg> (long option since dpkg 1.18.8).
+I<sign-command> will get all the arguments
+that B<gpg> would have gotten. I<sign-command>
+should not contain spaces or any other shell metacharacters.
+
+=item B<-k>, B<--sign-key=>I<key-id>
+
+Specify a key-ID to use when signing packages (long option since dpkg 1.18.8).
+
+=item B<-us>, B<--unsigned-source>
+
+Do not sign the source package (long option since dpkg 1.18.8).
+
+=item B<-ui>, B<--unsigned-buildinfo>
+
+Do not sign the B<.buildinfo> file (since dpkg 1.18.19).
+
+=item B<-uc>, B<--unsigned-changes>
+
+Do not sign the B<.buildinfo> and B<.changes> files
+(long option since dpkg 1.18.8).
+
+=item B<--no-sign>
+
+Do not sign any file, this includes the source package, the B<.buildinfo>
+file and the B<.changes> file (since dpkg 1.18.20).
+
+=item B<--force-sign>
+
+Force the signing of the resulting files (since dpkg 1.17.0), regardless of
+B<-us>, B<--unsigned-source>,
+B<-ui>, B<--unsigned-buildinfo>,
+B<-uc>, B<--unsigned-changes>
+or other internal heuristics.
+
+=item B<-sn>
+
+=item B<-ss>
+
+=item B<-sA>
+
+=item B<-sk>
+
+=item B<-su>
+
+=item B<-sr>
+
+=item B<-sK>
+
+=item B<-sU>
+
+=item B<-sR>
+
+=item B<-i>, B<--diff-ignore>[=I<regex>]
+
+=item B<-I>, B<--tar-ignore>[=I<pattern>]
+
+=item B<-z>, B<--compression-level=>I<level>
+
+=item B<-Z>, B<--compression=>I<compressor>
+
+Passed unchanged to B<dpkg-source>. See its manual page.
+
+=item B<--source-option=>I<opt>
+
+Pass option I<opt> to B<dpkg-source> (since dpkg 1.15.6).
+Can be used multiple times.
+
+=item B<--changes-option=>I<opt>
+
+Pass option I<opt> to B<dpkg-genchanges> (since dpkg 1.15.6).
+Can be used multiple times.
+
+=item B<--admindir=>I<dir>
+
+=item B<--admindir> I<dir>
+
+Change the location of the B<dpkg> database (since dpkg 1.14.0).
+The default location is I<%ADMINDIR%>.
+
+=item B<-?>, B<--help>
+
+Show the usage message and exit.
+
+=item B<--version>
+
+Show the version and exit.
+
+=back
+
+=head1 ENVIRONMENT
+
+=head2 External environment
+
+=over
+
+=item B<DEB_CHECK_COMMAND>
+
+If set, it will be used as the command to check the B<.changes> file
+(since dpkg 1.17.6).
+Overridden by the B<--check-command> option.
+
+=item B<DEB_SIGN_KEYID>
+
+If set, it will be used to sign the B<.changes> and B<.dsc> files
+(since dpkg 1.17.2).
+Overridden by the B<--sign-key> option.
+
+=item B<DEB_BUILD_OPTIONS>
+
+If set, it will contain a space-separated list of options that might
+affect the build process in I<debian/rules>, and the behavior of some
+dpkg commands.
+
+With B<nocheck> the B<DEB_CHECK_COMMAND> variable will be ignored.
+With B<parallel=>I<N> the parallel jobs will be set to I<N>,
+overridden by the B<--jobs-try> option.
+
+=item B<DEB_BUILD_PROFILES>
+
+If set, it will be used as the active build profile(s) for the package
+being built (since dpkg 1.17.2).
+It is a space separated list of profile names.
+Overridden by the B<-P> option.
+
+=item B<DPKG_COLORS>
+
+Sets the color mode (since dpkg 1.18.5).
+The currently accepted values are: B<auto> (default), B<always> and
+B<never>.
+
+=item B<DPKG_NLS>
+
+If set, it will be used to decide whether to activate Native Language Support,
+also known as internationalization (or i18n) support (since dpkg 1.19.0).
+The accepted values are: B<0> and B<1> (default).
+
+=back
+
+=head2 Internal environment
+
+Even if B<dpkg-buildpackage> exports some variables, B<debian/rules>
+should not rely on their presence and should instead use the
+respective interface to retrieve the needed values, because that
+file is the main entry point to build packages and running it
+standalone should be supported.
+
+=over
+
+=item B<DEB_BUILD_*>
+
+=item B<DEB_HOST_*>
+
+=item B<DEB_TARGET_*>
+
+B<dpkg-architecture> is called with the B<-a> and B<-t>
+parameters forwarded. Any variable that is output by its B<-s>
+option is integrated in the build environment.
+
+=item B<DEB_RULES_REQUIRES_ROOT>
+
+This variable is set to the value obtained from the B<Rules-Requires-Root>
+field or from the command-line.
+When set, it will be a valid value for the B<Rules-Requires-Root> field.
+It is used to notify B<debian/rules> whether the B<rootless-builds.txt>
+specification is supported.
+
+=item B<DEB_GAIN_ROOT_CMD>
+
+This variable is set to I<gain-root-command> when the field
+B<Rules-Requires-Root> is set to a value different to B<no> and
+B<binary-targets>.
+
+=item B<SOURCE_DATE_EPOCH>
+
+This variable is set to the Unix timestamp since the epoch of the
+latest entry in I<debian/changelog>, if it is not already defined.
+
+=back
+
+=head1 FILES
+
+=over
+
+=item I<%PKGCONFDIR%/buildpackage.conf>
+
+System wide configuration file
+
+=item I<$XDG_CONFIG_HOME/dpkg/buildpackage.conf> or
+
+=item I<$HOME/.config/dpkg/buildpackage.conf>
+
+User configuration file.
+
+=back
+
+=head1 NOTES
+
+=head2 Compiler flags are no longer exported
+
+Between dpkg 1.14.17 and 1.16.1, B<dpkg-buildpackage>
+exported compiler flags (B<CFLAGS>, B<CXXFLAGS>, B<FFLAGS>,
+B<CPPFLAGS> and B<LDFLAGS>) with values as returned
+by B<dpkg-buildflags>. This is no longer the case.
+
+=head2 Default build targets
+
+B<dpkg-buildpackage> is using the B<build-arch> and
+B<build-indep> targets since dpkg 1.16.2. Those targets are thus
+mandatory. But to avoid breakages of existing packages, and ease
+the transition, if the source package does not build both architecture
+independent and dependent binary packages (since dpkg 1.18.8) it will
+fallback to use the B<build> target if B<make -f debian/rules -qn>
+I<build-target> returns 2 as exit code.
+
+=head1 BUGS
+
+It should be possible to specify spaces and shell metacharacters
+and initial arguments for
+I<gain-root-command> and I<sign-command>.
+
+=head1 SEE ALSO
+
+B<dpkg-source>(1),
+B<dpkg-architecture>(1),
+B<dpkg-buildflags>(1),
+B<dpkg-genbuildinfo>(1),
+B<dpkg-genchanges>(1),
+B<fakeroot>(1),
+B<lintian>(1),
+B<gpg>(1).