DEBUILD(1) | General Commands Manual | DEBUILD(1) |
debuild - build a Debian package
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.
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:
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.
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.
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.
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:
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.
For details, see above.
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_DPKG_BUILDPACKAGE_OPTS="-k'Julian Gilbey <jdg@debian.org>' -sa"
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.
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)
The original debuild program was written by Christoph Lameter <clameter@debian.org>. The current version has been written by Julian Gilbey <jdg@debian.org>.
Debian Utilities | DEBIAN |