debuild - Online in the Cloud

PROGRAM:

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 .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 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 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-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 environment variables except for TERM,
HOME, LOGNAME, GNUPGHOME, PGPPATH, GPG_AGENT_INFO, DBUS_SESSION_BUS_ADDRESS, FAKEROOTKEY,
DEB_*, the (C, CPP, CXX, LD and F)FLAGS variables and their _APPEND 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 --preserve-envvar envvar (which can also
be written as -e envvar 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.

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 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. Note that if any of
the hooks from clean-hook to final-clean (inclusive) are used, debuild will emulate some
sections of the dpkg-buildpackage process rather than running them directly, as dpkg-
buildpackage does not support hooks. 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, -B, or -A 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. (Run even if we are not calling lintian.)

signing-hook
Run after calling lintian 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, %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 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.

If var ends in an asterisk ("*") then all variables with names that match the
portion of var before the asterisk will be preserved.

--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 behaviour, 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 directory exists before starting the
build. This is the default behaviour.

--username username
When signing, use debrsign instead of debsign. username specifies 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. 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_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 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 configuration file might contain the line:

DEBUILD_DPKG_BUILDPACKAGE_OPTS="-k'Julian Gilbey <[email protected]>' -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 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.

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

Use debuild online using onworks.net services