Adding upstream version 2.23.7.upstream/2.23.7upstream

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

1 files changed, 462 insertions, 0 deletions

diff --git a/scripts/debuild.1 b/scripts/debuild.1
new file mode 100644
index 0000000..2232c73
--- /dev/null
+++ b/scripts/debuild.1
@@ -0,0 +1,462 @@
+.TH DEBUILD 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
+.SH NAME
+debuild \- build a Debian package
+.SH SYNOPSIS
+\fBdebuild\fR [\fIdebuild options\fR] [\fIdpkg-buildpackage options\fR]
+[\fB\-\-lintian-opts\fR \fIlintian options\fR]
+.br
+\fBdebuild\fR [\fIdebuild options\fR] \-\-
+\fBbinary\fR|\fBbinary-arch\fR|\fBbinary-indep\fR|\fBclean\fR ...
+.SH DESCRIPTION
+\fBdebuild\fR creates all the files necessary for uploading a Debian
+package.  It first runs \fBdpkg-buildpackage\fR, then runs
+\fBlintian\fR on the \fI.changes\fR file created
+(assuming that \fBlintian\fR is installed), and
+finally signs the appropriate files (using \fBdebsign\fR(1) to do
+this instead of \fBdpkg-buildpackage\fR(1) itself; all relevant
+key-signing options are passed on).
+Signing will be skipped if the distribution is \fIUNRELEASED\fR, unless
+\fBdpkg-buildpackage\fR's \fB\-\-force-sign\fR option is used.
+Parameters can be passed to \fBdpkg-buildpackage\fR
+and \fBlintian\fR, where the parameters to the latter are
+indicated with the \fB\-\-lintian-opts\fR option.
+The allowable options in this case are
+\fB\-\-lintian\fR and \fB\-\-no-lintian\fR to force or skip the
+\fBlintian\fR step, respectively. The default is to run
+\fBlintian\fR.  There are also various options
+available for setting and preserving environment variables, as
+described below in the Environment Variables section.  In this method
+of running \fBdebuild\fR, we also save a build log to the
+file \fI../<package>_<version>_<arch>.build\fR.
+.PP
+An alternative way of using \fBdebuild\fR is to use one or more of the
+parameters \fBbinary\fR, \fBbinary-arch\fR, \fBbinary-indep\fR and
+\fBclean\fR, in which case \fBdebuild\fR will attempt to gain root
+privileges and then run \fIdebian/rules\fR with the given parameters.
+A \fB\-\-rootcmd=\fIgain-root-command\fR or
+\fB\-r\fIgain-root-command\fR option may be used to specify a method
+of gaining root privileges.  The \fIgain-root-command\fR is likely to
+be one of \fIfakeroot\fR, \fIsudo\fR or \fIsuper\fR.  See below for
+further discussion of this point.  Again, the environment preservation
+options may be used.  In this case, \fBdebuild\fR will also attempt to
+run \fBdpkg-checkbuilddeps\fR first; this can be explicitly requested
+or switched off using the options \fB\-D\fR and \fB\-d\fR
+respectively.  Note also that if either of these or a \fB\-r\fR option
+is specified in the configuration file option
+\fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR, then it will be recognised even in
+this method of invocation of \fBdebuild\fR.
+.PP
+\fBdebuild\fR also reads the \fBdevscripts\fR configuration files as
+described below.  This allows default options to be given.
+.SH "Directory name checking"
+In common with several other scripts in the \fBdevscripts\fR package,
+\fBdebuild\fR will climb the directory tree until it finds a
+\fIdebian/changelog\fR file before attempting to build the package.
+As a safeguard against stray files causing potential problems, it will
+examine the name of the parent directory once it finds the
+\fIdebian/changelog\fR file, and check that the directory name
+corresponds to the package name.  Precisely how it does this is
+controlled by two configuration file variables
+\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR and \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR, and
+their corresponding command-line options \fB\-\-check-dirname-level\fR
+and \fB\-\-check-dirname-regex\fR.
+.PP
+\fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR can take the following values:
+.TP
+.B 0
+Never check the directory name.
+.TP
+.B 1
+Only check the directory name if we have had to change directory in
+our search for \fIdebian/changelog\fR.  This is the default behaviour.
+.TP
+.B 2
+Always check the directory name.
+.PP
+The directory name is checked by testing whether the current directory
+name (as determined by \fBpwd\fR(1)) matches the regex given by the
+configuration file option \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR or by the
+command line option \fB\-\-check-dirname-regex\fR \fIregex\fR.  Here
+\fIregex\fR is a Perl regex (see \fBperlre\fR(3perl)), which will be
+anchored at the beginning and the end.  If \fIregex\fR contains a '/',
+then it must match the full directory path.  If not, then it must
+match the full directory name.  If \fIregex\fR contains the string
+\'PACKAGE', this will be replaced by the source package name, as
+determined from the \fIchangelog\fR.  The default value for the regex is:
+\'PACKAGE(-.+)?', thus matching directory names such as PACKAGE and
+PACKAGE-version.
+.SH ENVIRONMENT VARIABLES
+As environment variables can affect the building of a package, often
+unintentionally, \fBdebuild\fR sanitises the environment by removing
+all environment variables except for \fBTERM\fR, \fBHOME\fR, \fBLOGNAME\fR,
+\fBGNUPGHOME\fR, \fBPGPPATH\fR, \fBGPG_AGENT_INFO\fR, \fBGPG_TTY\fR,
+\fBDBUS_SESSION_BUS_ADDRESS\fR, \fBFAKEROOTKEY\fR, \fBDEBEMAIL\fR,
+\fBDEB_\fI*\fR, the (\fBC\fR, \fBCPP\fR, \fBCXX\fR, \fBLD\fR and
+\fBF\fR)\fBFLAGS\fR variables and their \fB_APPEND\fR counterparts and the
+locale variables \fBLANG\fR and \fBLC_\fI*\fR.  \fBTERM\fR is set to `dumb'
+if it is unset, and \fBPATH\fR is set to "/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11".
+.PP
+If a particular environment variable is required to be passed through
+untouched to the build process, this may be specified by using a
+\fB\-\-preserve-envvar\fR \fIenvvar\fR (which can also be written as
+\fB\-e\fR \fIenvvar\fR option).  The environment may be left untouched
+by using the \fB\-\-preserve-env\fR option.  However, even in this
+case, the \fBPATH\fR will be set to the sane value described above.  The
+\fBonly\fR way to prevent \fBPATH\fR from being reset is to specify a
+\fB\-\-preserve-envvar PATH\fR option.  But you are warned that using
+programs from non-standard locations can easily result in the package
+being broken, as it will not be able to be built on standard systems.
+.PP
+Note that one may add directories to the beginning of the sanitised
+\fBPATH\fR, using the \fB\-\-prepend\-path\fR option. This is useful when
+one wishes to use tools such as \fBccache\fR or \fBdistcc\fR for building.
+.PP
+It is also possible to avoid having to type something like
+\fIFOO\fB=\fIbar \fBdebuild \-e \fIFOO\fR by writing \fBdebuild \-e
+\fIFOO\fB=\fIbar\fR or the long form \fBdebuild \-\-set\-envvar
+\fIFOO\fB=\fIbar\fR.
+.SH "SUPERUSER REQUIREMENTS"
+\fBdebuild\fR needs to be run as superuser to function properly.
+There are three fundamentally different ways to do this.  The first,
+and preferable, method is to use some root-gaining command.  The best
+one to use is probably \fBfakeroot\fR(1), since it does not involve
+granting any genuine privileges.  \fBsuper\fR(1) and \fBsudo\fR(1) are
+also possibilities.  If no \fB\-r\fR (or \fB\-\-rootcmd\fR) option is
+given (and recall that \fBdpkg-buildpackage\fR also accepts a \fB\-r\fR
+option) and neither of the following methods is used, then
+\fB\-rfakeroot\fR will silently be assumed.
+.PP
+The second method is to use some command such as \fBsu\fR(1) to become
+root, and then to do everything as root.  Note, though, that
+\fBlintian\fR will abort if it is run as root or setuid root; this can
+be overcome using the \fB\-\-allow-root\fR option of \fBlintian\fR if
+you know what you are doing.
+.PP
+The third possible method is to have \fBdebuild\fR installed as setuid
+root.  This is not the default method, and will have to be installed
+as such by the system administrator.  It must also be realised that
+anyone who can run \fBdebuild\fR as root or setuid root has \fBfull
+access to the whole machine\fR.  This method is therefore not
+recommended, but will work.  \fBdebuild\fR could be installed with
+mode 4754, so that only members of the owning group could run it.  A
+disadvantage of this method would be that other users would then not
+be able to use the program.  There are many other variants of this
+option involving multiple copies of \fBdebuild\fR, or the use of
+programs such as \fBsudo\fR or \fBsuper\fR to grant root privileges to
+users selectively.  If the sysadmin wishes to do this, she should use
+the \fBdpkg-statoverride\fR program to change the permissions of
+\fI/usr/bin/debuild\fR.  This will ensure that these permissions are
+preserved across upgrades.
+.SH HOOKS
+\fBdebuild\fR supports a number of hooks when running
+\fBdpkg\-buildpackage\fR.  Note that the hooks \fBdpkg-buildpackage\fR
+to \fBlintian\fR (inclusive) are passed through to \fBdpkg-buildpackage\fR
+using its corresponding \fB\-\-hook-\fR\fIname\fR option.  The available
+hooks are as follows:
+.TP
+\fBdpkg-buildpackage-hook
+Run before \fBdpkg-buildpackage\fR begins by calling \fBdpkg-checkbuilddeps\fR.
+.IP
+Hook is run inside the unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBinit\fR hook.
+.TP
+\fBclean-hook
+Run before \fBdpkg-buildpackage\fR runs \fBdebian/rules clean\fR to clean the
+source tree.  (Run even if the tree is not being cleaned because \fB\-nc\fR
+is used.)
+.IP
+Hook is run inside the unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBpreclean\fR hook.
+.TP
+\fBdpkg-source-hook
+Run after cleaning the tree and before running \fBdpkg-source\fR.  (Run even
+if \fBdpkg-source\fR is not being called because \fB\-b\fR, \fB\-B\fR, or \fB\-A\fR is used.)
+.IP
+Hook is run inside the unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBsource\fR hook.
+.TP
+\fBdpkg-build-hook\fR
+Run after \fBdpkg-source\fR and before calling \fBdebian/rules build\fR.  (Run
+even if this is a source-only build, so \fBdebian/rules build\fR is not
+being called.)
+.IP
+Hook is run inside the unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBbuild\fR hook.
+.TP
+\fBdpkg-binary-hook
+Run between \fBdebian/rules build\fR and \fBdebian/rules binary\fR(\fB\-arch\fR).  Run
+\fBonly\fR if a binary package is being built.
+.IP
+Hook is run inside the unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBbinary\fR hook.
+.TP
+\fBdpkg-genchanges-hook
+Run after the binary package is built and before calling
+\fBdpkg-genchanges\fR.
+.IP
+Hook is run inside the unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBchanges\fR hook.
+.TP
+\fBfinal-clean-hook
+Run after \fBdpkg-genchanges\fR and before the final \fBdebian/rules clean\fR.
+(Run even if we are not cleaning the tree post-build, which is the
+default.)
+.IP
+Hook is run inside the unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBpostclean\fR hook.
+.TP
+\fBlintian-hook
+Run (once) before calling \fBlintian\fR.  (Run even if we are
+not calling \fBlintian\fR.)
+.IP
+Hook is run from parent directory of unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBcheck\fR hook.
+.TP
+\fBsigning-hook
+Run after calling \fBlintian\fR before any signing takes place.
+(Run even if we are not signing anything.)
+.IP
+Hook is run from parent directory of unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBsign\fR hook, but is run by \fBdebuild\fR.
+.TP
+\fBpost-dpkg-buildpackage-hook
+Run after everything has finished.
+.IP
+Hook is run from parent directory of unpacked source.
+.IP
+Corresponds to \fBdpkg\fR's \fBdone\fR hook, but is run by \fBdebuild\fR.
+.PP
+A hook command can be specified either in the configuration file as,
+for example, DEBUILD_SIGNING_HOOK='foo' (note the hyphens change into
+underscores!) or as a command line option \fB\-\-signing\-hook-foo\fR.
+The command will have certain percent substitutions made on it: \fB%%\fR
+will be replaced by a single \fB%\fR sign, \fB%p\fR will be replaced by the
+package name, \fB%v\fR by the package version number, \fB%s\fR by the source
+version number, \fB%u\fR by the upstream version number.  Neither \fB%s\fR nor \fB%u\fR
+will contain an epoch.  \fB%a\fR will be \fB1\fR if the immediately following
+action is to be performed and \fB0\fR if not (for example, in the
+\fBdpkg-source\fR hook, \fB%a\fR will become \fB1\fR if \fBdpkg-source\fR is to be run and \fB0\fR
+if not).  Then it will be handed to the shell to deal with, so it can
+include redirections and stuff.  For example, to only run the
+\fBdpkg-source\fR hook if \fBdpkg-source\fR is to be run, the hook could be
+something like: "if [ %a \-eq 1 ]; then ...; fi".
+.PP
+\fBPlease take care with hooks\fR, as misuse of them can lead to
+packages which FTBFS (fail to build from source).  They can be useful
+for taking snapshots of things or the like.
+.SH "OPTIONS"
+For details, see above.
+.TP
+.B \-\-no-conf\fR, \fB\-\-noconf
+Do not read any configuration files.  This can only be used as the
+first option given on the command-line.
+.TP
+.BI \-\-rootcmd= "gain-root-command\fR, " \-r gain-root-command
+Command to gain root (or fake root) privileges.
+.TP
+.B \-\-preserve\-env
+Do not clean the environment, except for PATH.
+.TP
+.BI \-\-preserve\-envvar= "var\fR, " \-e var
+Do not clean the \fIvar\fR variable from the environment.
+.IP
+If \fIvar\fR ends in an asterisk ("*") then all variables with names
+that match the portion of \fIvar\fR before the asterisk will be
+preserved.
+.TP
+.BI \-\-set\-envvar= var = "value\fR, " \-e var = value
+Set the environment variable \fIvar\fR to \fIvalue\fR and do not
+remove it from the environment.
+.TP
+.BI \-\-prepend\-path= "value "
+Once the normalized PATH has been set, prepend \fIvalue\fR
+to it.
+.TP
+.B \-\-lintian
+Run \fBlintian\fR after \fBdpkg-buildpackage\fR.  This is the default
+behaviour, and it overrides any configuration file directive to the
+contrary.
+.TP
+.B \-\-no\-lintian
+Do not run \fBlintian\fR after \fBdpkg-buildpackage\fR.
+.TP
+.B \-\-no\-tgz\-check
+Even if we're running \fBdpkg-buildpackage\fR and the version number
+has a Debian revision, do not check that the \fI.orig.tar.gz\fR file or \fI.orig\fR
+directory exists before starting the build.
+.TP
+.B \-\-tgz\-check
+If we're running \fBdpkg-buildpackage\fR and the version number has a
+Debian revision, check that the \fI.orig.tar.gz\fR file or \fI.orig\fR directory
+exists before starting the build.  This is the default behaviour.
+.TP
+\fB\-\-username\fR \fIusername\fR
+When signing, use \fBdebrsign\fR instead of \fBdebsign\fR.
+\fIusername\fR specifies the credentials to be used.
+.TP
+\fB\-\-\fIfoo\fB\-hook\fR=\fIhook\fR
+Set a hook as described above.  If \fIhook\fR is blank, this unsets
+the hook.
+.TP
+\fB\-\-clear\-hooks\fR
+Clears all hooks.  They may be reinstated by later command line
+options.
+.TP
+\fB\-\-check-dirname-level\fR \fIN\fR
+See the above section \fBDirectory name checking\fR for an explanation of
+this option.
+.TP
+\fB\-\-check-dirname-regex\fR \fIregex\fR
+See the above section \fBDirectory name checking\fR for an explanation of
+this option.
+.TP
+\fB\-d\fR
+Do not run \fBdpkg-checkbuilddeps\fR to check build dependencies.
+.TP
+\fB\-D\fR
+Run \fBdpkg-checkbuilddeps\fR to check build dependencies.
+.SH "CONFIGURATION VARIABLES"
+The two configuration files \fI/etc/devscripts.conf\fR and
+\fI~/.devscripts\fR are sourced by a shell in that order to set
+configuration variables.  Command line options can be used to override
+some of these configuration file settings, otherwise the
+\fB\-\-no\-conf\fR option can be used to prevent reading these files.
+Environment variable settings are ignored when these configuration
+files are read.  The currently recognised variables are:
+.TP
+.B DEBUILD_PRESERVE_ENV
+If this is set to \fIyes\fR, then it is the same as the
+\fB\-\-preserve\-env\fR command line parameter being used.
+.TP
+.B DEBUILD_PRESERVE_ENVVARS
+Which environment variables to preserve.  This should be a
+comma-separated list of variables.  This corresponds to using possibly
+multiple \fB\-\-preserve\-envvar\fR or \fB\-e\fR options.
+.TP
+.BI DEBUILD_SET_ENVVAR_ var = value
+This corresponds to \fB\-\-set\-envvar=\fIvar\fB=\fIvalue\fR.
+.TP
+.B DEBUILD_PREPEND_PATH
+This corresponds to \fB\-\-prepend\-path\fR.
+.TP
+.B DEBUILD_ROOTCMD
+Setting this variable to \fIprog\fR is the equivalent of
+\fB\-r\fIprog\fR.
+.TP
+.B DEBUILD_TGZ_CHECK
+Setting this variable to \fIno\fR is the same as the
+\fB\-\-no\-tgz\-check\fR command line option.
+.TP
+.B DEBUILD_SIGNING_USERNAME
+Setting this variable is the same as using the \fB\-\-username\fR
+command line option.
+.TP
+.B DEBUILD_DPKG_BUILDPACKAGE_OPTS
+These are options which should be passed to the invocation of
+\fBdpkg-buildpackage\fR.  They are given before any command-line
+options.  Due to issues of shell quoting, if a word containing spaces
+is required as a single option, extra quotes will be required.  For
+example, to ensure that your own GPG key is always used, even for
+sponsored uploads, the configuration file might contain the line:
+.IP
+.nf
+DEBUILD_DPKG_BUILDPACKAGE_OPTS="\-k'Julian Gilbey <jdg@debian.org>' \-sa"
+.fi
+.IP
+which gives precisely two options.  Without the extra single quotes,
+\fBdpkg-buildpackage\fR would reasonably complain that \fIGilbey\fR is
+an unrecognised option (it doesn't start with a \fB\-\fR sign).
+.IP
+Also, if this option contains any \fB\-r\fR, \fB\-d\fR or \fB\-D\fR
+options, these will always be taken account of by \fBdebuild\fR.  Note
+that a \fB\-r\fR option in this variable will override the setting in
+.BR DEBUILD_ROOTCMD .
+.TP
+\fBDEBUILD_\fIFOO\fB_HOOK
+The hook variable for the \fIfoo\fR hook.  See the section on hooks
+above for more details.  By default, this is empty.
+.TP
+.B DEBUILD_LINTIAN
+Should we run \fBlintian\fR?  If this is set to \fIno\fR, then
+\fBlintian\fR will not be run.
+.TP
+.B DEBUILD_LINTIAN_OPTS
+These are options which should be passed to the invocation of
+\fBlintian\fR.  They are given before any command-line options, and
+the usage of this variable is as described for the
+\fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR variable.
+.TP
+.BR DEVSCRIPTS_CHECK_DIRNAME_LEVEL ", " DEVSCRIPTS_CHECK_DIRNAME_REGEX
+See the above section \fBDirectory name checking\fR for an explanation of
+these variables.  Note that these are package-wide configuration
+variables, and will therefore affect all \fBdevscripts\fR scripts
+which check their value, as described in their respective manpages and
+in \fBdevscripts.conf\fR(5).
+.SH EXAMPLES
+To build your own package, simply run \fBdebuild\fR from inside the
+source tree.  \fBdpkg-buildpackage\fR(1) options may be given on the
+command line.
+.PP
+The typical command line options to build only the binary package(s)
+without signing the .changes file (or the non-existent .dsc file):
+.IP
+.nf
+debuild \-i \-us \-uc \-b
+.fi
+.PP
+Change the \fB\-b\fR to \fB\-S\fR to build only a source package.
+.PP
+An example using \fBlintian\fR to check the
+resulting packages and passing options to it:
+.IP
+.nf
+debuild \-\-lintian-opts \-i
+.fi
+.PP
+Note the order of options here: the \fBdebuild\fR options come first,
+then the \fBdpkg-buildpackage\fR ones, then finally the checker
+options.  (And \fBlintian\fR is called by default.)  If you find
+yourself using the same \fBdpkg-buildpackage\fR options repeatedly,
+consider using the \fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR configuration file
+option as described above.
+.PP
+To build a package for a sponsored upload, given
+\fIfoobar_1.0-1.dsc\fR and the respective source files, run something
+like the following commands:
+.IP
+.nf
+dpkg-source \-x foobar_1.0-1.dsc
+cd foobar-1.0
+debuild \-k0x12345678
+.fi
+.PP
+where 0x12345678 is replaced by your GPG key ID or other key
+identifier such as your email address.  Again, you could also use the
+\fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR configuration file option as described
+above to avoid having to type the \fB\-k\fR option each time you do a
+sponsored upload.
+.SH "SEE ALSO"
+.BR chmod (1),
+.BR debsign (1),
+.BR dpkg-buildpackage (1),
+.BR dpkg-checkbuilddeps (1),
+.BR fakeroot (1),
+.BR lintian (1),
+.BR su (1),
+.BR sudo (1),
+.BR super (1),
+.BR devscripts.conf (5),
+.BR dpkg-statoverride (8)
+.SH AUTHOR
+The original \fBdebuild\fR program was written by Christoph Lameter
+<clameter@debian.org>.  The current version has been written by Julian
+Gilbey <jdg@debian.org>.