debuild creates all the files necessary for uploading a Debian
package. It first runs dpkg-buildpackage, then runs
lintian and/or linda on the .changes file created
(assuming that lintian and/or linda is installed), and
finally signs the .changes and/or .dsc files as
appropriate (using debsign(1) to do this instead of
dpkg-buildpackage(1) itself; all relevant key-signing options
are passed on). Parameters can be passed to dpkg-buildpackage,
lintian and linda, where the parameters to the latter are
indicated with the --lintian-opts and --linda-opts
options respectively. The allowable options in this case are
--lintian and --no-lintian to force or skip the
lintian step, respectively, and similarly --linda and
--no-linda for linda. The default is to run
lintian but not linda. 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 debuild, we also save a build log to the
file ../<package>_<version>_<arch>.build.
An alternative way of using debuild is to use one or more of the
parameters binary, binary-arch, binary-indep and
clean, in which case debuild will attempt to gain root
privileges and then run debian/rules with the given parameters.
A --rootcmd=gain-root-command or
-rgain-root-command option may be used to specify a method
of gaining root privileges. The gain-root-command is likely to
be one of fakeroot, sudo or super. See below for
further discussion of this point. Again, the environment preservation
options may be used. In this case, debuild will also attempt to
run dpkg-checkbuilddeps first; this can be explicitly requested
or switched off using the options -D and -d
respectively. Note also that if either of these or a -r option
is specified in the configuration file option
DEBUILD_DPKG_BUILDPACKAGE_OPTS, then it will be recognised even in
this method of invocation of debuild.
debuild also reads the devscripts configuration files as
described below. This allows default options to be given.
Directory name checking
In common with several other scripts in the devscripts package,
debuild will climb the directory tree until it finds a
debian/changelog 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
debian/changelog file, and check that the directory name
corresponds to the package name. Precisely how it does this is
controlled by two configuration file variables
DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and
their corresponding command-line options --check-dirname-level
and --check-dirname-regex.
DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
0
Never check the directory name.
1
Only check the directory name if we have had to change directory in
our search for debian/changelog. This is the default behaviour.
2
Always check the directory name.
The directory name is checked by testing whether the current directory
name (as determined by pwd(1)) matches the regex given by the
configuration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the
command line option --check-dirname-regexregex. Here
regex is a Perl regex (see perlre(3perl)), which will be
anchored at the beginning and the end. If regex contains a '/',
then it must match the full directory path. If not, then it must
match the full directory name. If regex contains the string
'PACKAGE', this will be replaced by the source package name, as
determined from the changelog. The default value for the regex is:
'PACKAGE(-.*)?', thus matching directory names such as PACKAGE and
PACKAGE-version.
ENVIRONMENT VARIABLES
As environment variables can affect the building of a package, often
unintentionally, debuild sanitises the environment by removing
all environment variables except for TERM, HOME, LOGNAME, GNUPGHOME,
PGPPATH, GPG_AGENT_INFO, FAKEROOTKEY, DEB_* and the locale variables
LANG and LC_*. TERM is set to `dumb' if it is unset, and PATH is set
to "/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11".
If a particular environment variable is required to be passed through
untouched to the build process, this may be specified by using a
--preserve-envvarenvvar (which can also be written as
-eenvvar option). The environment may be left untouched
by using the --preserve-env option. However, even in this
case, the PATH will be set to the sane value described above. The
only way to prevent PATH from being reset is to specify a
--preserve-envvar PATH 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.
It is also possible to avoid having to type something like
FOO=bar debuild -e FOO by writing debuild -e
FOO=bar or the long form debuild --set-envvar
FOO=bar.
SUPERUSER REQUIREMENTS
debuild 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 fakeroot(1), since it does not involve
granting any genuine privileges. super(1) and sudo(1) are
also possibilities. If no -r (or --rootcmd) option is
given (and recall that dpkg-buildpackage also accepts a -r
option) and neither of the following methods is used, then
-rfakeroot will silently be assumed.
The second method is to use some command such as su(1) to become
root, and then to do everything as root. Note, though, that
lintian will abort if it is run as root or setuid root; this can
be overcome using the --allow-root option of lintian if
you know what you are doing.
The third possible method is to have debuild 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 debuild as root or setuid root has full
access to the whole machine. This method is therefore not
recommended, but will work. debuild 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 debuild, or the use of
programs such as sudo or super to grant root privileges to
users selectively. If the sysadmin wishes to do this, she should use
the dpkg-statoverride program to change the permissions of
/usr/bin/debuild. This will ensure that these permissions are
preserved across upgrades.
HOOKS
debuild supports a number of hooks when running
dpkg-buildpackage. The available hooks are as follows:
dpkg-buildpackage-hook
Run before dpkg-buildpackage begins by calling dpkg-checkbuilddeps.
clean-hook
Run before dpkg-buildpackage runs debian/rules clean to clean the
source tree. (Run even if the tree is not being cleaned because -nc
is used.)
dpkg-source-hook
Run after cleaning the tree and before running dpkg-source. (Run even
if dpkg-source is not being called because -b or -B is used.)
dpkg-build-hook
Run after dpkg-source and before calling debian/rules build. (Run
even if this is a source-only build, so debian/rules build is not
being called.)
dpkg-binary-hook
Run between debian/rules build and debian/rules binary(-arch). Run
ONLY if a binary package is being built.
dpkg-genchanges-hook
Run after the binary package is built and before calling
dpkg-genchanges.
final-clean-hook
Run after dpkg-genchanges and before the final debian/rules clean.
(Run even if we are not cleaning the tree post-build, which is the
default.)
lintian-hook
Run (once) before calling lintian and/or linda. (Run even if we are
not calling either.)
signing-hook
Run after calling lintian and/or linda before any signing takes place.
(Run even if we are not signing anything.)
post-dpkg-buildpackage-hook
Run after everything has finished.
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 --signing-hook-foo.
The command will have certain percent substitutions made on it: %%
will be replaced by a single % sign, %p will be replaced by the
package name, %v by the package version number, %a will be 1 if the
immediately following action is to be performed and 0 if not (for
example, in the dpkg-source hook, %a will become 1 if dpkg-source is
to be run and 0 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 dpkg-source hook if dpkg-source is to be run, the hook could
be something like: "if [ %a -eq 1 ]; then ...; fi".
Please take care with hooks, 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.
Finally, only dpkg-buildpackage-hook and the hooks from lintian-hook
onwards can be used if dpkg-cross is installed. (This is
because internally, debuild reimplements
dpkg-buildpackage, but it does not attempt to reimplement the
dpkg-cross replacement of this script.)
OPTIONS
For details, see above.
--no-conf, --noconf
Do not read any configuration files. This can only be used as the
first option given on the command-line.
--rootcmd=gain-root-command, -rgain-root-command
Command to gain root (or fake root) privileges.
--preserve-env
Do not clean the environment, except for PATH.
--preserve-envvar=var, -evar
Do not clean the var variable from the environment.
--set-envvar=var=value, -evar=value
Set the environment variable var to value and do not
remove it from the environment.
--lintian
Run lintian after dpkg-buildpackage. This is the default
behaviour, and it overrides any configuration file directive to the
contrary.
--no-lintian
Do not run lintian after dpkg-buildpackage.
--linda
Run linda after dpkg-buildpackage.
--no-linda
Do not run linda after dpkg-buildpackage. This is the
default behaviour.
--no-tgz-check
Even if we're running dpkg-buildpackage and the version number
has a Debian revision, do not check that the .orig.tar.gz file or .orig
directory exists before starting the build.
--tgz-check
If we're running dpkg-buildpackage and the version number has a
Debian revision, check that the .orig.tar.gz file or .orig directory
exists before starting the build. This is the default behaviour.
--foo-hook=hook
Set a hook as described above. If hook is blank, this unsets
the hook.
--clear-hooks
Clears all hooks. They may be reinstated by later command line
options.
--check-dirname-levelN
See the above section "Directory name checking" for an explanation of
this option.
--check-dirname-regexregex
See the above section "Directory name checking" for an explanation of
this option.
-d
Do not run dpkg-checkbuilddeps to check build dependencies.
-D
Run dpkg-checkbuilddeps to check build dependencies.
CONFIGURATION VARIABLES
The two configuration files /etc/devscripts.conf and
~/.devscripts 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
--no-conf 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:
DEBUILD_PRESERVE_ENV
If this is set to yes, then it is the same as the
--preserve-env command line parameter being used.
DEBUILD_PRESERVE_ENVVARS
Which environment variables to preserve. This should be a
comma-separated list of variables. This corresponds to using possibly
multiple --preserve-envvar or -e options.
DEBUILD_SET_ENVVAR_var=value
This corresponds to --set-envvar=var=value.
DEBUILD_ROOTCMD
Setting this variable to prog is the equivalent of
-rprog.
DEBUILD_TGZ_CHECK
Setting this variable to no is the same as the
--no-tgz-check command line option.
DEBUILD_DPKG_BUILDPACKAGE_OPTS
These are options which should be passed to the invocation of
dpkg-buildpackage. 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 config file might contain the line:
which gives precisely two options. Without the extra single quotes,
dpkg-buildpackage would reasonably complain that Gilbey is
an unrecognised option (it doesn't start with a `-' sign).
Also, if this option contains any -r, -d or -D
options, these will always be taken account of by debuild. Note
that a -r option in this variable will override the setting in
DEBUILD_ROOTCMD.
DEBUILD_FOO_HOOK
The hook variable for the
foo hook. See the section on hooks
above for more details. By default, this is empty.
DEBUILD_LINTIAN
Should we run lintian? If this is set to no, then
lintian will not be run.
DEBUILD_LINTIAN_OPTS
These are options which should be passed to the invocation of
lintian. They are given before any command-line options, and
the usage of this variable is as described for the
DEBUILD_DPKG_BUILDPACKAGE_OPTS variable.
DEBUILD_LINDA
Should we run linda? If this is set to yes, then
linda will be run.
DEBUILD_LINDA_OPTS
These are options which should be passed to the invocation of
linda. They are given before any command-line options, and
the usage of this variable is as described for the
DEBUILD_DPKG_BUILDPACKAGE_OPTS variable.
See the above section "Directory name checking" for an explanation of
these variables. Note that these are package-wide configuration
variables, and will therefore affect all devscripts scripts
which check their value, as described in their respective manpages and
in devscripts.conf(5).
EXAMPLES
To build your own package, simply run debuild from inside the
source tree. dpkg-buildpackage(1) options may be given on the
command line.
The typical command line options to build only the binary package(s)
without signing the .changes file (or the non-existent .dsc file):
debuild -i -us -uc -b
Change the "-b" to "-S" to build only a source package.
An example using both lintian and linda to check the
resulting packages, and also passing options to them both:
Note the order of options here: the debuild options come first,
then the dpkg-buildpackage ones, then finally the checker
options. (And lintian is called by default.) If you find
yourself using the same dpkg-buildpackage options repeatedly,
consider using the DEBUILD_DPKG_BUILDPACKAGE_OPTS configuration file
option as described above.
To build a package for a sponsored upload, given
foobar_1.0-1.dsc and the respective source files, run something
like the following commands:
dpkg-source -x foobar_1.0-1.dsc
cd foobar-1.0
debuild -k0x12345678
where 0x12345678 is replaced by your GPG key ID or other key
identifier such as your email address. Again, you could also use the
DEBUILD_DPKG_BUILDPACKAGE_OPTS configuration file option as described
above to avoid having to type the -k option each time you do a
sponsored upload.
The original debuild program was written by Christoph Lameter
<clameter@debian.org>. The current version has been written by Julian
Gilbey <jdg@debian.org>.
