.TH DEBUILD 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*- .SH NAME debuild \- build a Debian package .SH SYNOPSIS \fBdebuild\fR [\fIdebuild options\fR] [\fIdpkg-buildpackage options\fR] [\fB\-\-lintian-opts\fR \fIlintian options\fR] .br \fBdebuild\fR [\fIdebuild options\fR] \-\- \fBbinary\fR|\fBbinary-arch\fR|\fBbinary-indep\fR|\fBclean\fR ... .SH DESCRIPTION \fBdebuild\fR creates all the files necessary for uploading a Debian package. It first runs \fBdpkg-buildpackage\fR, then runs \fBlintian\fR on the \fI.changes\fR file created (assuming that \fBlintian\fR is installed), and finally signs the appropriate files (using \fBdebsign\fR(1) to do this instead of \fBdpkg-buildpackage\fR(1) itself; all relevant key-signing options are passed on). Signing will be skipped if the distribution is \fIUNRELEASED\fR, unless \fBdpkg-buildpackage\fR's \fB\-\-force-sign\fR option is used. Parameters can be passed to \fBdpkg-buildpackage\fR and \fBlintian\fR, where the parameters to the latter are indicated with the \fB\-\-lintian-opts\fR option. The allowable options in this case are \fB\-\-lintian\fR and \fB\-\-no-lintian\fR to force or skip the \fBlintian\fR step, respectively. The default is to run \fBlintian\fR. 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 \fBdebuild\fR, we also save a build log to the file \fI../__.build\fR. .PP An alternative way of using \fBdebuild\fR is to use one or more of the parameters \fBbinary\fR, \fBbinary-arch\fR, \fBbinary-indep\fR and \fBclean\fR, in which case \fBdebuild\fR will attempt to gain root privileges and then run \fIdebian/rules\fR with the given parameters. A \fB\-\-rootcmd=\fIgain-root-command\fR or \fB\-r\fIgain-root-command\fR option may be used to specify a method of gaining root privileges. The \fIgain-root-command\fR is likely to be one of \fIfakeroot\fR, \fIsudo\fR or \fIsuper\fR. See below for further discussion of this point. Again, the environment preservation options may be used. In this case, \fBdebuild\fR will also attempt to run \fBdpkg-checkbuilddeps\fR first; this can be explicitly requested or switched off using the options \fB\-D\fR and \fB\-d\fR respectively. Note also that if either of these or a \fB\-r\fR option is specified in the configuration file option \fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR, then it will be recognised even in this method of invocation of \fBdebuild\fR. .PP \fBdebuild\fR also reads the \fBdevscripts\fR configuration files as described below. This allows default options to be given. .SH "Directory name checking" In common with several other scripts in the \fBdevscripts\fR package, \fBdebuild\fR will climb the directory tree until it finds a \fIdebian/changelog\fR 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 \fIdebian/changelog\fR file, and check that the directory name corresponds to the package name. Precisely how it does this is controlled by two configuration file variables \fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR and \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR, and their corresponding command-line options \fB\-\-check-dirname-level\fR and \fB\-\-check-dirname-regex\fR. .PP \fBDEVSCRIPTS_CHECK_DIRNAME_LEVEL\fR can take the following values: .TP .B 0 Never check the directory name. .TP .B 1 Only check the directory name if we have had to change directory in our search for \fIdebian/changelog\fR. This is the default behaviour. .TP .B 2 Always check the directory name. .PP The directory name is checked by testing whether the current directory name (as determined by \fBpwd\fR(1)) matches the regex given by the configuration file option \fBDEVSCRIPTS_CHECK_DIRNAME_REGEX\fR or by the command line option \fB\-\-check-dirname-regex\fR \fIregex\fR. Here \fIregex\fR is a Perl regex (see \fBperlre\fR(3perl)), which will be anchored at the beginning and the end. If \fIregex\fR contains a '/', then it must match the full directory path. If not, then it must match the full directory name. If \fIregex\fR contains the string \'PACKAGE', this will be replaced by the source package name, as determined from the \fIchangelog\fR. The default value for the regex is: \'PACKAGE(-.+)?', thus matching directory names such as PACKAGE and PACKAGE-version. .SH ENVIRONMENT VARIABLES As environment variables can affect the building of a package, often unintentionally, \fBdebuild\fR sanitises the environment by removing all environment variables except for \fBTERM\fR, \fBHOME\fR, \fBLOGNAME\fR, \fBGNUPGHOME\fR, \fBPGPPATH\fR, \fBGPG_AGENT_INFO\fR, \fBGPG_TTY\fR, \fBDBUS_SESSION_BUS_ADDRESS\fR, \fBFAKEROOTKEY\fR, \fBDEBEMAIL\fR, \fBDEB_\fI*\fR, the (\fBC\fR, \fBCPP\fR, \fBCXX\fR, \fBLD\fR and \fBF\fR)\fBFLAGS\fR variables and their \fB_APPEND\fR counterparts and the locale variables \fBLANG\fR and \fBLC_\fI*\fR. \fBTERM\fR is set to `dumb' if it is unset, and \fBPATH\fR is set to "/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11". .PP If a particular environment variable is required to be passed through untouched to the build process, this may be specified by using a \fB\-\-preserve-envvar\fR \fIenvvar\fR (which can also be written as \fB\-e\fR \fIenvvar\fR option). The environment may be left untouched by using the \fB\-\-preserve-env\fR option. However, even in this case, the \fBPATH\fR will be set to the sane value described above. The \fBonly\fR way to prevent \fBPATH\fR from being reset is to specify a \fB\-\-preserve-envvar PATH\fR 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. .PP Note that one may add directories to the beginning of the sanitised \fBPATH\fR, using the \fB\-\-prepend\-path\fR option. This is useful when one wishes to use tools such as \fBccache\fR or \fBdistcc\fR for building. .PP It is also possible to avoid having to type something like \fIFOO\fB=\fIbar \fBdebuild \-e \fIFOO\fR by writing \fBdebuild \-e \fIFOO\fB=\fIbar\fR or the long form \fBdebuild \-\-set\-envvar \fIFOO\fB=\fIbar\fR. .SH "SUPERUSER REQUIREMENTS" \fBdebuild\fR 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 \fBfakeroot\fR(1), since it does not involve granting any genuine privileges. \fBsuper\fR(1) and \fBsudo\fR(1) are also possibilities. If no \fB\-r\fR (or \fB\-\-rootcmd\fR) option is given (and recall that \fBdpkg-buildpackage\fR also accepts a \fB\-r\fR option) and neither of the following methods is used, then \fB\-rfakeroot\fR will silently be assumed. .PP The second method is to use some command such as \fBsu\fR(1) to become root, and then to do everything as root. Note, though, that \fBlintian\fR will abort if it is run as root or setuid root; this can be overcome using the \fB\-\-allow-root\fR option of \fBlintian\fR if you know what you are doing. .PP The third possible method is to have \fBdebuild\fR 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 \fBdebuild\fR as root or setuid root has \fBfull access to the whole machine\fR. This method is therefore not recommended, but will work. \fBdebuild\fR 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 \fBdebuild\fR, or the use of programs such as \fBsudo\fR or \fBsuper\fR to grant root privileges to users selectively. If the sysadmin wishes to do this, she should use the \fBdpkg-statoverride\fR program to change the permissions of \fI/usr/bin/debuild\fR. This will ensure that these permissions are preserved across upgrades. .SH HOOKS \fBdebuild\fR supports a number of hooks when running \fBdpkg\-buildpackage\fR. Note that the hooks \fBdpkg-buildpackage\fR to \fBlintian\fR (inclusive) are passed through to \fBdpkg-buildpackage\fR using its corresponding \fB\-\-hook-\fR\fIname\fR option. The available hooks are as follows: .TP \fBdpkg-buildpackage-hook Run before \fBdpkg-buildpackage\fR begins by calling \fBdpkg-checkbuilddeps\fR. .IP Hook is run inside the unpacked source. .IP Corresponds to \fBdpkg\fR's \fBinit\fR hook. .TP \fBclean-hook Run before \fBdpkg-buildpackage\fR runs \fBdebian/rules clean\fR to clean the source tree. (Run even if the tree is not being cleaned because \fB\-nc\fR is used.) .IP Hook is run inside the unpacked source. .IP Corresponds to \fBdpkg\fR's \fBpreclean\fR hook. .TP \fBdpkg-source-hook Run after cleaning the tree and before running \fBdpkg-source\fR. (Run even if \fBdpkg-source\fR is not being called because \fB\-b\fR, \fB\-B\fR, or \fB\-A\fR is used.) .IP Hook is run inside the unpacked source. .IP Corresponds to \fBdpkg\fR's \fBsource\fR hook. .TP \fBdpkg-build-hook\fR Run after \fBdpkg-source\fR and before calling \fBdebian/rules build\fR. (Run even if this is a source-only build, so \fBdebian/rules build\fR is not being called.) .IP Hook is run inside the unpacked source. .IP Corresponds to \fBdpkg\fR's \fBbuild\fR hook. .TP \fBdpkg-binary-hook Run between \fBdebian/rules build\fR and \fBdebian/rules binary\fR(\fB\-arch\fR). Run \fBonly\fR if a binary package is being built. .IP Hook is run inside the unpacked source. .IP Corresponds to \fBdpkg\fR's \fBbinary\fR hook. .TP \fBdpkg-genchanges-hook Run after the binary package is built and before calling \fBdpkg-genchanges\fR. .IP Hook is run inside the unpacked source. .IP Corresponds to \fBdpkg\fR's \fBchanges\fR hook. .TP \fBfinal-clean-hook Run after \fBdpkg-genchanges\fR and before the final \fBdebian/rules clean\fR. (Run even if we are not cleaning the tree post-build, which is the default.) .IP Hook is run inside the unpacked source. .IP Corresponds to \fBdpkg\fR's \fBpostclean\fR hook. .TP \fBlintian-hook Run (once) before calling \fBlintian\fR. (Run even if we are not calling \fBlintian\fR.) .IP Hook is run from parent directory of unpacked source. .IP Corresponds to \fBdpkg\fR's \fBcheck\fR hook. .TP \fBsigning-hook Run after calling \fBlintian\fR before any signing takes place. (Run even if we are not signing anything.) .IP Hook is run from parent directory of unpacked source. .IP Corresponds to \fBdpkg\fR's \fBsign\fR hook, but is run by \fBdebuild\fR. .TP \fBpost-dpkg-buildpackage-hook Run after everything has finished. .IP Hook is run from parent directory of unpacked source. .IP Corresponds to \fBdpkg\fR's \fBdone\fR hook, but is run by \fBdebuild\fR. .PP 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 \fB\-\-signing\-hook-foo\fR. The command will have certain percent substitutions made on it: \fB%%\fR will be replaced by a single \fB%\fR sign, \fB%p\fR will be replaced by the package name, \fB%v\fR by the package version number, \fB%s\fR by the source version number, \fB%u\fR by the upstream version number. Neither \fB%s\fR nor \fB%u\fR will contain an epoch. \fB%a\fR will be \fB1\fR if the immediately following action is to be performed and \fB0\fR if not (for example, in the \fBdpkg-source\fR hook, \fB%a\fR will become \fB1\fR if \fBdpkg-source\fR is to be run and \fB0\fR 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 \fBdpkg-source\fR hook if \fBdpkg-source\fR is to be run, the hook could be something like: "if [ %a \-eq 1 ]; then ...; fi". .PP \fBPlease take care with hooks\fR, 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. .SH "OPTIONS" For details, see above. .TP .B \-\-no-conf\fR, \fB\-\-noconf Do not read any configuration files. This can only be used as the first option given on the command-line. .TP .BI \-\-rootcmd= "gain-root-command\fR, " \-r gain-root-command Command to gain root (or fake root) privileges. .TP .B \-\-preserve\-env Do not clean the environment, except for PATH. .TP .BI \-\-preserve\-envvar= "var\fR, " \-e var Do not clean the \fIvar\fR variable from the environment. .IP If \fIvar\fR ends in an asterisk ("*") then all variables with names that match the portion of \fIvar\fR before the asterisk will be preserved. .TP .BI \-\-set\-envvar= var = "value\fR, " \-e var = value Set the environment variable \fIvar\fR to \fIvalue\fR and do not remove it from the environment. .TP .BI \-\-prepend\-path= "value " Once the normalized PATH has been set, prepend \fIvalue\fR to it. .TP .B \-\-lintian Run \fBlintian\fR after \fBdpkg-buildpackage\fR. This is the default behaviour, and it overrides any configuration file directive to the contrary. .TP .B \-\-no\-lintian Do not run \fBlintian\fR after \fBdpkg-buildpackage\fR. .TP .B \-\-no\-tgz\-check Even if we're running \fBdpkg-buildpackage\fR and the version number has a Debian revision, do not check that the \fI.orig.tar.gz\fR file or \fI.orig\fR directory exists before starting the build. .TP .B \-\-tgz\-check If we're running \fBdpkg-buildpackage\fR and the version number has a Debian revision, check that the \fI.orig.tar.gz\fR file or \fI.orig\fR directory exists before starting the build. This is the default behaviour. .TP \fB\-\-username\fR \fIusername\fR When signing, use \fBdebrsign\fR instead of \fBdebsign\fR. \fIusername\fR specifies the credentials to be used. .TP \fB\-\-\fIfoo\fB\-hook\fR=\fIhook\fR Set a hook as described above. If \fIhook\fR is blank, this unsets the hook. .TP \fB\-\-clear\-hooks\fR Clears all hooks. They may be reinstated by later command line options. .TP \fB\-\-check-dirname-level\fR \fIN\fR See the above section \fBDirectory name checking\fR for an explanation of this option. .TP \fB\-\-check-dirname-regex\fR \fIregex\fR See the above section \fBDirectory name checking\fR for an explanation of this option. .TP \fB\-d\fR Do not run \fBdpkg-checkbuilddeps\fR to check build dependencies. .TP \fB\-D\fR Run \fBdpkg-checkbuilddeps\fR to check build dependencies. .SH "CONFIGURATION VARIABLES" The two configuration files \fI/etc/devscripts.conf\fR and \fI~/.devscripts\fR 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 \fB\-\-no\-conf\fR 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: .TP .B DEBUILD_PRESERVE_ENV If this is set to \fIyes\fR, then it is the same as the \fB\-\-preserve\-env\fR command line parameter being used. .TP .B DEBUILD_PRESERVE_ENVVARS Which environment variables to preserve. This should be a comma-separated list of variables. This corresponds to using possibly multiple \fB\-\-preserve\-envvar\fR or \fB\-e\fR options. .TP .BI DEBUILD_SET_ENVVAR_ var = value This corresponds to \fB\-\-set\-envvar=\fIvar\fB=\fIvalue\fR. .TP .B DEBUILD_PREPEND_PATH This corresponds to \fB\-\-prepend\-path\fR. .TP .B DEBUILD_ROOTCMD Setting this variable to \fIprog\fR is the equivalent of \fB\-r\fIprog\fR. .TP .B DEBUILD_TGZ_CHECK Setting this variable to \fIno\fR is the same as the \fB\-\-no\-tgz\-check\fR command line option. .TP .B DEBUILD_SIGNING_USERNAME Setting this variable is the same as using the \fB\-\-username\fR command line option. .TP .B DEBUILD_DPKG_BUILDPACKAGE_OPTS These are options which should be passed to the invocation of \fBdpkg-buildpackage\fR. 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: .IP .nf DEBUILD_DPKG_BUILDPACKAGE_OPTS="\-k'Julian Gilbey ' \-sa" .fi .IP which gives precisely two options. Without the extra single quotes, \fBdpkg-buildpackage\fR would reasonably complain that \fIGilbey\fR is an unrecognised option (it doesn't start with a \fB\-\fR sign). .IP Also, if this option contains any \fB\-r\fR, \fB\-d\fR or \fB\-D\fR options, these will always be taken account of by \fBdebuild\fR. Note that a \fB\-r\fR option in this variable will override the setting in .BR DEBUILD_ROOTCMD . .TP \fBDEBUILD_\fIFOO\fB_HOOK The hook variable for the \fIfoo\fR hook. See the section on hooks above for more details. By default, this is empty. .TP .B DEBUILD_LINTIAN Should we run \fBlintian\fR? If this is set to \fIno\fR, then \fBlintian\fR will not be run. .TP .B DEBUILD_LINTIAN_OPTS These are options which should be passed to the invocation of \fBlintian\fR. They are given before any command-line options, and the usage of this variable is as described for the \fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR variable. .TP .BR DEVSCRIPTS_CHECK_DIRNAME_LEVEL ", " DEVSCRIPTS_CHECK_DIRNAME_REGEX See the above section \fBDirectory name checking\fR for an explanation of these variables. Note that these are package-wide configuration variables, and will therefore affect all \fBdevscripts\fR scripts which check their value, as described in their respective manpages and in \fBdevscripts.conf\fR(5). .SH EXAMPLES To build your own package, simply run \fBdebuild\fR from inside the source tree. \fBdpkg-buildpackage\fR(1) options may be given on the command line. .PP The typical command line options to build only the binary package(s) without signing the .changes file (or the non-existent .dsc file): .IP .nf debuild \-i \-us \-uc \-b .fi .PP Change the \fB\-b\fR to \fB\-S\fR to build only a source package. .PP An example using \fBlintian\fR to check the resulting packages and passing options to it: .IP .nf debuild \-\-lintian-opts \-i .fi .PP Note the order of options here: the \fBdebuild\fR options come first, then the \fBdpkg-buildpackage\fR ones, then finally the checker options. (And \fBlintian\fR is called by default.) If you find yourself using the same \fBdpkg-buildpackage\fR options repeatedly, consider using the \fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR configuration file option as described above. .PP To build a package for a sponsored upload, given \fIfoobar_1.0-1.dsc\fR and the respective source files, run something like the following commands: .IP .nf dpkg-source \-x foobar_1.0-1.dsc cd foobar-1.0 debuild \-k0x12345678 .fi .PP where 0x12345678 is replaced by your GPG key ID or other key identifier such as your email address. Again, you could also use the \fBDEBUILD_DPKG_BUILDPACKAGE_OPTS\fR configuration file option as described above to avoid having to type the \fB\-k\fR option each time you do a sponsored upload. .SH "SEE ALSO" .BR chmod (1), .BR debsign (1), .BR dpkg-buildpackage (1), .BR dpkg-checkbuilddeps (1), .BR fakeroot (1), .BR lintian (1), .BR su (1), .BR sudo (1), .BR super (1), .BR devscripts.conf (5), .BR dpkg-statoverride (8) .SH AUTHOR The original \fBdebuild\fR program was written by Christoph Lameter . The current version has been written by Julian Gilbey .