Linux Manpages Online - man.cx manual pages

SYNOPSIS

debuild [debuild options] [dpkg-buildpackage options] [--lintian-opts lintian options]
debuild [debuild options] -- binary|binary-arch|binary-indep|clean ...

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.