1DEBUILD(1) General Commands Manual DEBUILD(1)
2
6 debuild - build a Debian package
7
9 debuild [debuild options] [dpkg-buildpackage options] [--lintian-opts
10 lintian options]
11 debuild [debuild options] -- binary|binary-arch|binary-indep|clean ...
12
14 debuild creates all the files necessary for uploading a Debian package.
15 It first runs dpkg-buildpackage, then runs lintian on the .changes file
16 created (assuming that lintian is installed), and finally signs the
17 appropriate files (using debsign(1) to do this instead of dpkg-build‐
18 package(1) itself; all relevant key-signing options are passed on).
19 Signing will be skipped if the distribution is UNRELEASED, unless dpkg-
20 buildpackage's --force-sign option is used. Parameters can be passed
21 to dpkg-buildpackage and lintian, where the parameters to the latter
22 are indicated with the --lintian-opts option. The allowable options in
23 this case are --lintian and --no-lintian to force or skip the lintian
24 step, respectively. The default is to run lintian. There are also var‐
25 ious options available for setting and preserving environment vari‐
26 ables, as described below in the Environment Variables section. In
27 this method of running debuild, we also save a build log to the file
28 ../<package>_<version>_<arch>.build.
29 An alternative way of using debuild is to use one or more of the param‐
31 eters binary, binary-arch, binary-indep and clean, in which case
32 debuild will attempt to gain root privileges and then run debian/rules
33 with the given parameters. A --rootcmd=gain-root-command or -rgain-
34 root-command option may be used to specify a method of gaining root
35 privileges. The gain-root-command is likely to be one of fakeroot,
36 sudo or super. See below for further discussion of this point. Again,
37 the environment preservation options may be used. In this case,
38 debuild will also attempt to run dpkg-checkbuilddeps first; this can be
39 explicitly requested or switched off using the options -D and -d
40 respectively. Note also that if either of these or a -r option is
41 specified in the configuration file option DEBUILD_DPKG_BUILDPACK‐
42 AGE_OPTS, then it will be recognised even in this method of invocation
43 of debuild.
44 debuild also reads the devscripts configuration files as described
46 below. This allows default options to be given.
47
49 In common with several other scripts in the devscripts package, debuild
50 will climb the directory tree until it finds a debian/changelog file
51 before attempting to build the package. As a safeguard against stray
52 files causing potential problems, it will examine the name of the par‐
53 ent directory once it finds the debian/changelog file, and check that
54 the directory name corresponds to the package name. Precisely how it
55 does this is controlled by two configuration file variables
56 DEVSCRIPTS_CHECK_DIRNAME_LEVEL and DEVSCRIPTS_CHECK_DIRNAME_REGEX, and
57 their corresponding command-line options --check-dirname-level and
58 --check-dirname-regex.
59 DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
61 0 Never check the directory name.
63 1 Only check the directory name if we have had to change directory
65 in our search for debian/changelog. This is the default behav‐
66 iour.
67 2 Always check the directory name.
69 The directory name is checked by testing whether the current directory
71 name (as determined by pwd(1)) matches the regex given by the configu‐
72 ration file option DEVSCRIPTS_CHECK_DIRNAME_REGEX or by the command
73 line option --check-dirname-regex regex. Here regex is a Perl regex
74 (see perlre(3perl)), which will be anchored at the beginning and the
75 end. If regex contains a '/', then it must match the full directory
76 path. If not, then it must match the full directory name. If regex
77 contains the string ´PACKAGE', this will be replaced by the source
78 package name, as determined from the changelog. The default value for
79 the regex is: ´PACKAGE(-.+)?', thus matching directory names such as
80 PACKAGE and PACKAGE-version.
81
83 As environment variables can affect the building of a package, often
84 unintentionally, debuild sanitises the environment by removing all
85 environment variables except for TERM, HOME, LOGNAME, GNUPGHOME, PGP‐
86 PATH, GPG_AGENT_INFO, GPG_TTY, DBUS_SESSION_BUS_ADDRESS, FAKEROOTKEY,
87 DEBEMAIL, DEB_*, the (C, CPP, CXX, LD and F)FLAGS variables and their
88 _APPEND counterparts and the locale variables LANG and LC_*. TERM is
89 set to `dumb' if it is unset, and PATH is set to
90 "/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11".
91 If a particular environment variable is required to be passed through
93 untouched to the build process, this may be specified by using a --pre‐
94 serve-envvar envvar (which can also be written as -e envvar option).
95 The environment may be left untouched by using the --preserve-env
96 option. However, even in this case, the PATH will be set to the sane
97 value described above. The only way to prevent PATH from being reset
98 is to specify a --preserve-envvar PATH option. But you are warned that
99 using programs from non-standard locations can easily result in the
100 package being broken, as it will not be able to be built on standard
101 systems.
102 Note that one may add directories to the beginning of the sanitised
104 PATH, using the --prepend-path option. This is useful when one wishes
105 to use tools such as ccache or distcc for building.
106 It is also possible to avoid having to type something like FOO=bar
108 debuild -e FOO by writing debuild -e FOO=bar or the long form debuild
109 --set-envvar FOO=bar.
110
112 debuild needs to be run as superuser to function properly. There are
113 three fundamentally different ways to do this. The first, and prefer‐
114 able, method is to use some root-gaining command. The best one to use
115 is probably fakeroot(1), since it does not involve granting any genuine
116 privileges. super(1) and sudo(1) are also possibilities. If no -r (or
117 --rootcmd) option is given (and recall that dpkg-buildpackage also
118 accepts a -r option) and neither of the following methods is used, then
119 -rfakeroot will silently be assumed.
120 The second method is to use some command such as su(1) to become root,
122 and then to do everything as root. Note, though, that lintian will
123 abort if it is run as root or setuid root; this can be overcome using
124 the --allow-root option of lintian if you know what you are doing.
125 The third possible method is to have debuild installed as setuid root.
127 This is not the default method, and will have to be installed as such
128 by the system administrator. It must also be realised that anyone who
129 can run debuild as root or setuid root has full access to the whole
130 machine. This method is therefore not recommended, but will work.
131 debuild could be installed with mode 4754, so that only members of the
132 owning group could run it. A disadvantage of this method would be that
133 other users would then not be able to use the program. There are many
134 other variants of this option involving multiple copies of debuild, or
135 the use of programs such as sudo or super to grant root privileges to
136 users selectively. If the sysadmin wishes to do this, she should use
137 the dpkg-statoverride program to change the permissions of
138 /usr/bin/debuild. This will ensure that these permissions are pre‐
139 served across upgrades.
140
142 debuild supports a number of hooks when running dpkg-buildpackage.
143 Note that the hooks dpkg-buildpackage to lintian (inclusive) are passed
144 through to dpkg-buildpackage using its corresponding --hook-name
145 option. The available hooks are as follows:
146 dpkg-buildpackage-hook
148 Run before dpkg-buildpackage begins by calling dpkg-checkbuild‐
149 deps.
150 Hook is run inside the unpacked source.
152 Corresponds to dpkg's init hook.
154 clean-hook
156 Run before dpkg-buildpackage runs debian/rules clean to clean
157 the source tree. (Run even if the tree is not being cleaned
158 because -nc is used.)
159 Hook is run inside the unpacked source.
161 Corresponds to dpkg's preclean hook.
163 dpkg-source-hook
165 Run after cleaning the tree and before running dpkg-source.
166 (Run even if dpkg-source is not being called because -b, -B, or
167 -A is used.)
168 Hook is run inside the unpacked source.
170 Corresponds to dpkg's source hook.
172 dpkg-build-hook
174 Run after dpkg-source and before calling debian/rules build.
175 (Run even if this is a source-only build, so debian/rules build
176 is not being called.)
177 Hook is run inside the unpacked source.
179 Corresponds to dpkg's build hook.
181 dpkg-binary-hook
183 Run between debian/rules build and debian/rules binary(-arch).
184 Run only if a binary package is being built.
185 Hook is run inside the unpacked source.
187 Corresponds to dpkg's binary hook.
189 dpkg-genchanges-hook
191 Run after the binary package is built and before calling dpkg-
192 genchanges.
193 Hook is run inside the unpacked source.
195 Corresponds to dpkg's changes hook.
197 final-clean-hook
199 Run after dpkg-genchanges and before the final debian/rules
200 clean. (Run even if we are not cleaning the tree post-build,
201 which is the default.)
202 Hook is run inside the unpacked source.
204 Corresponds to dpkg's postclean hook.
206 lintian-hook
208 Run (once) before calling lintian. (Run even if we are not
209 calling lintian.)
210 Hook is run from parent directory of unpacked source.
212 Corresponds to dpkg's check hook.
214 signing-hook
216 Run after calling lintian before any signing takes place. (Run
217 even if we are not signing anything.)
218 Hook is run from parent directory of unpacked source.
220 Corresponds to dpkg's sign hook, but is run by debuild.
222 post-dpkg-buildpackage-hook
224 Run after everything has finished.
225 Hook is run from parent directory of unpacked source.
227 Corresponds to dpkg's done hook, but is run by debuild.
229 A hook command can be specified either in the configuration file as,
231 for example, DEBUILD_SIGNING_HOOK='foo' (note the hyphens change into
232 underscores!) or as a command line option --signing-hook-foo. The com‐
233 mand will have certain percent substitutions made on it: %% will be
234 replaced by a single % sign, %p will be replaced by the package name,
235 %v by the package version number, %s by the source version number, %u
236 by the upstream version number. Neither %s nor %u will contain an
237 epoch. %a will be 1 if the immediately following action is to be per‐
238 formed and 0 if not (for example, in the dpkg-source hook, %a will
239 become 1 if dpkg-source is to be run and 0 if not). Then it will be
240 handed to the shell to deal with, so it can include redirections and
241 stuff. For example, to only run the dpkg-source hook if dpkg-source is
242 to be run, the hook could be something like: "if [ %a -eq 1 ]; then
243 ...; fi".
244 Please take care with hooks, as misuse of them can lead to packages
246 which FTBFS (fail to build from source). They can be useful for taking
247 snapshots of things or the like.
248
250 For details, see above.
251 --no-conf, --noconf
253 Do not read any configuration files. This can only be used as
254 the first option given on the command-line.
255 --rootcmd=gain-root-command, -rgain-root-command
257 Command to gain root (or fake root) privileges.
258 --preserve-env
260 Do not clean the environment, except for PATH.
261 --preserve-envvar=var, -evar
263 Do not clean the var variable from the environment.
264 If var ends in an asterisk ("*") then all variables with names
266 that match the portion of var before the asterisk will be pre‐
267 served.
268 --set-envvar=var=value, -evar=value
270 Set the environment variable var to value and do not remove it
271 from the environment.
272 --prepend-path=value
274 Once the normalized PATH has been set, prepend value to it.
275 --lintian
277 Run lintian after dpkg-buildpackage. This is the default behav‐
278 iour, and it overrides any configuration file directive to the
279 contrary.
280 --no-lintian
282 Do not run lintian after dpkg-buildpackage.
283 --no-tgz-check
285 Even if we're running dpkg-buildpackage and the version number
286 has a Debian revision, do not check that the .orig.tar.gz file
287 or .orig directory exists before starting the build.
288 --tgz-check
290 If we're running dpkg-buildpackage and the version number has a
291 Debian revision, check that the .orig.tar.gz file or .orig
292 directory exists before starting the build. This is the default
293 behaviour.
294 --username username
296 When signing, use debrsign instead of debsign. username speci‐
297 fies the credentials to be used.
298 --foo-hook=hook
300 Set a hook as described above. If hook is blank, this unsets
301 the hook.
302 --clear-hooks
304 Clears all hooks. They may be reinstated by later command line
305 options.
306 --check-dirname-level N
308 See the above section Directory name checking for an explanation
309 of this option.
310 --check-dirname-regex regex
312 See the above section Directory name checking for an explanation
313 of this option.
314 -d Do not run dpkg-checkbuilddeps to check build dependencies.
316 -D Run dpkg-checkbuilddeps to check build dependencies.
318
320 The two configuration files /etc/devscripts.conf and ~/.devscripts are
321 sourced by a shell in that order to set configuration variables. Com‐
322 mand line options can be used to override some of these configuration
323 file settings, otherwise the --no-conf option can be used to prevent
324 reading these files. Environment variable settings are ignored when
325 these configuration files are read. The currently recognised variables
326 are:
327 DEBUILD_PRESERVE_ENV
329 If this is set to yes, then it is the same as the --preserve-env
330 command line parameter being used.
331 DEBUILD_PRESERVE_ENVVARS
333 Which environment variables to preserve. This should be a
334 comma-separated list of variables. This corresponds to using
335 possibly multiple --preserve-envvar or -e options.
336 DEBUILD_SET_ENVVAR_var=value
338 This corresponds to --set-envvar=var=value.
339 DEBUILD_PREPEND_PATH
341 This corresponds to --prepend-path.
342 DEBUILD_ROOTCMD
344 Setting this variable to prog is the equivalent of -rprog.
345 DEBUILD_TGZ_CHECK
347 Setting this variable to no is the same as the --no-tgz-check
348 command line option.
349 DEBUILD_SIGNING_USERNAME
351 Setting this variable is the same as using the --username com‐
352 mand line option.
353 DEBUILD_DPKG_BUILDPACKAGE_OPTS
355 These are options which should be passed to the invocation of
356 dpkg-buildpackage. They are given before any command-line
357 options. Due to issues of shell quoting, if a word containing
358 spaces is required as a single option, extra quotes will be
359 required. For example, to ensure that your own GPG key is
360 always used, even for sponsored uploads, the configuration file
361 might contain the line:
362 DEBUILD_DPKG_BUILDPACKAGE_OPTS="-k'Julian Gilbey <jdg@debian.org>' -sa"
364 which gives precisely two options. Without the extra single
366 quotes, dpkg-buildpackage would reasonably complain that Gilbey
367 is an unrecognised option (it doesn't start with a - sign).
368 Also, if this option contains any -r, -d or -D options, these
370 will always be taken account of by debuild. Note that a -r
371 option in this variable will override the setting in
372 DEBUILD_ROOTCMD.
373 DEBUILD_FOO_HOOK
375 The hook variable for the foo hook. See the section on hooks
376 above for more details. By default, this is empty.
377 DEBUILD_LINTIAN
379 Should we run lintian? If this is set to no, then lintian will
380 not be run.
381 DEBUILD_LINTIAN_OPTS
383 These are options which should be passed to the invocation of
384 lintian. They are given before any command-line options, and
385 the usage of this variable is as described for the
386 DEBUILD_DPKG_BUILDPACKAGE_OPTS variable.
387 DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
389 See the above section Directory name checking for an explanation
390 of these variables. Note that these are package-wide configura‐
391 tion variables, and will therefore affect all devscripts scripts
392 which check their value, as described in their respective man‐
393 pages and in devscripts.conf(5).
394
396 To build your own package, simply run debuild from inside the source
397 tree. dpkg-buildpackage(1) options may be given on the command line.
398 The typical command line options to build only the binary package(s)
400 without signing the .changes file (or the non-existent .dsc file):
401 debuild -i -us -uc -b
403 Change the -b to -S to build only a source package.
405 An example using lintian to check the resulting packages and passing
407 options to it:
408 debuild --lintian-opts -i
410 Note the order of options here: the debuild options come first, then
412 the dpkg-buildpackage ones, then finally the checker options. (And
413 lintian is called by default.) If you find yourself using the same
414 dpkg-buildpackage options repeatedly, consider using the
415 DEBUILD_DPKG_BUILDPACKAGE_OPTS configuration file option as described
416 above.
417 To build a package for a sponsored upload, given foobar_1.0-1.dsc and
419 the respective source files, run something like the following commands:
420 dpkg-source -x foobar_1.0-1.dsc
422 cd foobar-1.0
423 debuild -k0x12345678
424 where 0x12345678 is replaced by your GPG key ID or other key identifier
426 such as your email address. Again, you could also use the
427 DEBUILD_DPKG_BUILDPACKAGE_OPTS configuration file option as described
428 above to avoid having to type the -k option each time you do a spon‐
429 sored upload.
430
432 chmod(1), debsign(1), dpkg-buildpackage(1), dpkg-checkbuilddeps(1),
433 fakeroot(1), lintian(1), su(1), sudo(1), super(1), devscripts.conf(5),
434 dpkg-statoverride(8)
435
437 The original debuild program was written by Christoph Lameter <clame‐
438 ter@debian.org>. The current version has been written by Julian Gilbey
439 <jdg@debian.org>.
440DEBIAN Debian Utilities DEBUILD(1)