diff options
Diffstat (limited to 'scripts/debuild.1')
| -rw-r--r-- | scripts/debuild.1 | 462 |
1 files changed, 462 insertions, 0 deletions
diff --git a/scripts/debuild.1 b/scripts/debuild.1 new file mode 100644 index 0000000..2232c73 --- /dev/null +++ b/scripts/debuild.1 @@ -0,0 +1,462 @@ +.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../<package>_<version>_<arch>.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 <jdg@debian.org>' \-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 +<clameter@debian.org>. The current version has been written by Julian +Gilbey <jdg@debian.org>. |