Ubuntu Manpage: debuild - build a Debian package

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