devscripts/scripts/debuild.1

.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>.