debuild(1) - phpMan

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 appropriate files (using debsign(1) to do this in-
stead of dpkg-buildpackage(1) itself; all relevant key-signing options are passed on).
Signing 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 al-
lowable 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 avail-
able for setting and preserving environment variables, as described below in the Environ-
ment 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, bi-
nary-arch, binary-indep and clean, in which case debuild will attempt to gain root privi-
leges 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 fur-
ther 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 ex-
plicitly 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 DE-
BUILD_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 de-
fault options to be given.

Directory name checking
In common with several other scripts in the devscripts package, debuild will climb the di-
rectory tree until it finds a debian/changelog file before attempting to build the pack-
age. 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 DE-
VSCRIPTS_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 DE-
VSCRIPTS_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, de-
build sanitises the environment by removing all environment variables except for TERM,
HOME, LOGNAME, GNUPGHOME, PGPPATH, GPG_AGENT_INFO, GPG_TTY, DBUS_SESSION_BUS_ADDRESS,
FAKEROOTKEY, DEBEMAIL, 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 un-
set, 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 --pre-
serve-envvar PATH option. But you are warned that using programs from non-standard loca-
tions 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 writ-
ing 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 ev-
erything 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 ac-
cess to the whole machine. 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 pro-
gram to change the permissions of /usr/bin/debuild. This will ensure that these permis-
sions 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 option. The available hooks are as follows:

dpkg-buildpackage-hook
Run before dpkg-buildpackage begins by calling dpkg-checkbuilddeps.