debuild
DEBUILD(1) General Commands Manual DEBUILD(1)
NAME
debuild - build a Debian package
SYNOPSIS
debuild [debuild options] [dpkg-buildpackage options] [--lintian-opts
lintian options]
debuild [debuild options] -- binary|binary-arch|binary-indep|clean ...
DESCRIPTION
debuild creates all the files necessary for uploading a Debian package.
It first runs dpkg-buildpackage, then runs lintian on the .changes file
created (assuming that lintian is installed), and finally signs the ap-
propriate files (using debsign(1) to do this instead of dpkg-buildpack-
age(1) itself; all relevant key-signing options are passed on). Sign-
ing will be skipped if the distribution is UNRELEASED, unless dpkg-
buildpackage's --force-sign option is used. Parameters can be passed
to dpkg-buildpackage and lintian, where the parameters to the latter
are indicated with the --lintian-opts option. The allowable options in
this case are --lintian and --no-lintian to force or skip the lintian
step, respectively. The default is to run lintian. There are also var-
ious options available for setting and preserving environment vari-
ables, 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 param-
eters binary, binary-arch, binary-indep and clean, in which case de-
build 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, de-
build will also attempt to run dpkg-checkbuilddeps first; this can be
explicitly requested or switched off using the options -D and -d re-
spectively. Note also that if either of these or a -r option is speci-
fied in the configuration file option DEBUILD_DPKG_BUILDPACKAGE_OPTS,
then it will be recognised even in this method of invocation of de-
build.
debuild also reads the devscripts configuration files as described be-
low. 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 par-
ent 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 DE-
VSCRIPTS_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 behav-
iour.
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 configu-
ration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command
line option --check-dirname-regex regex. 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 en-
vironment variables except for TERM, HOME, LOGNAME, GNUPGHOME, PGPPATH,
GPG_AGENT_INFO, GPG_TTY, DBUS_SESSION_BUS_ADDRESS, FAKEROOTKEY, DEBE-
MAIL, DEB_*, the (C, CPP, CXX, LD and F)FLAGS variables and their _AP-
PEND counterparts 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 --pre-
serve-envvar envvar (which can also be written as -e envvar option).
The environment may be left untouched by using the --preserve-env op-
tion. 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.
Note that one may add directories to the beginning of the sanitised
PATH, using the --prepend-path option. This is useful when one wishes
to use tools such as ccache or distcc for building.
It is also possible to avoid having to type something like FOO=bar de-
build -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 prefer-
able, 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 ac-
cepts 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 ma-
chine. This method is therefore not recommended, but will work. de-
build 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/de-
build. This will ensure that these permissions are preserved across
upgrades.
HOOKS
debuild supports a number of hooks when running dpkg-buildpackage.
Note that the hooks dpkg-buildpackage to lintian (inclusive) are passed
through to dpkg-buildpackage using its corresponding --hook-name op-
tion. The available hooks are as follows:
dpkg-buildpackage-hook
Run before dpkg-buildpackage begins by calling dpkg-checkbuild-
deps.
Hook is run inside the unpacked source.
Corresponds to dpkg's init hook.
clean-hook
Run before dpkg-buildpackage runs debian/rules clean to clean
the source tree. (Run even if the tree is not being cleaned be-
cause -nc is used.)
Hook is run inside the unpacked source.
Corresponds to dpkg's preclean hook.
dpkg-source-hook
Run after cleaning the tree and before running dpkg-source.
(Run even if dpkg-source is not being called because -b, -B, or
-A is used.)
Hook is run inside the unpacked source.
Corresponds to dpkg's source hook.
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.)
Hook is run inside the unpacked source.
Corresponds to dpkg's build hook.
dpkg-binary-hook
Run between debian/rules build and debian/rules binary(-arch).
Run only if a binary package is being built.
Hook is run inside the unpacked source.
Corresponds to dpkg's binary hook.
dpkg-genchanges-hook
Run after the binary package is built and before calling dpkg-
genchanges.
Hook is run inside the unpacked source.
Corresponds to dpkg's changes hook.
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.)
Hook is run inside the unpacked source.
Corresponds to dpkg's postclean hook.
lintian-hook
Run (once) before calling lintian. (Run even if we are not
calling lintian.)
Hook is run from parent directory of unpacked source.
Corresponds to dpkg's check hook.
signing-hook
Run after calling lintian before any signing takes place. (Run
even if we are not signing anything.)
Hook is run from parent directory of unpacked source.
Corresponds to dpkg's sign hook, but is run by debuild.
post-dpkg-buildpackage-hook
Run after everything has finished.
Hook is run from parent directory of unpacked source.
Corresponds to dpkg's done hook, but is run by debuild.
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 com-
mand will have certain percent substitutions made on it: %% will be re-
placed by a single % sign, %p will be replaced by the package name, %v
by the package version number, %s by the source version number, %u by
the upstream version number. Neither %s nor %u will contain an epoch.
%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 ex-
ample, 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.
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.
If var ends in an asterisk ("*") then all variables with names
that match the portion of var before the asterisk will be pre-
served.
--set-envvar=var=value, -evar=value
Set the environment variable var to value and do not remove it
from the environment.
--prepend-path=value
Once the normalized PATH has been set, prepend value to it.
--lintian
Run lintian after dpkg-buildpackage. This is the default behav-
iour, and it overrides any configuration file directive to the
contrary.
--no-lintian
Do not run lintian after dpkg-buildpackage.
--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 di-
rectory exists before starting the build. This is the default
behaviour.
--username username
When signing, use debrsign instead of debsign. username speci-
fies the credentials to be used.
--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-level N
See the above section Directory name checking for an explanation
of this option.
--check-dirname-regex regex
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. Com-
mand 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_PREPEND_PATH
This corresponds to --prepend-path.
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_SIGNING_USERNAME
Setting this variable is the same as using the --username com-
mand 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 op-
tions. Due to issues of shell quoting, if a word containing
spaces is required as a single option, extra quotes will be re-
quired. For example, to ensure that your own GPG key is always
used, even for sponsored uploads, the configuration file might
contain the line:
DEBUILD_DPKG_BUILDPACKAGE_OPTS="-k'Julian Gilbey <jdg@debian.org>' -sa"
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 op-
tion in this variable will override the setting in DE-
BUILD_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 DE-
BUILD_DPKG_BUILDPACKAGE_OPTS variable.
DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
See the above section Directory name checking for an explanation
of these variables. Note that these are package-wide configura-
tion variables, and will therefore affect all devscripts scripts
which check their value, as described in their respective man-
pages 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 lintian to check the resulting packages and passing
options to it:
debuild --lintian-opts -i
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 DE-
BUILD_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 DE-
BUILD_DPKG_BUILDPACKAGE_OPTS configuration file option as described
above to avoid having to type the -k option each time you do a spon-
sored upload.
SEE ALSO
chmod(1), debsign(1), dpkg-buildpackage(1), dpkg-checkbuilddeps(1),
fakeroot(1), lintian(1), su(1), sudo(1), super(1), devscripts.conf(5),
dpkg-statoverride(8)
AUTHOR
The original debuild program was written by Christoph Lameter <clame-
ter@debian.org>. The current version has been written by Julian Gilbey
<jdg@debian.org>.
DEBIAN Debian Utilities DEBUILD(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2024
Hurricane Electric.
All Rights Reserved.