1DEBUILD(1)                  General Commands Manual                 DEBUILD(1)
2
3
4

NAME

6       debuild - build a Debian package
7

SYNOPSIS

9       debuild  [debuild  options] [dpkg-buildpackage options] [--lintian-opts
10       lintian options]
11       debuild [debuild options] -- binary|binary-arch|binary-indep|clean ...
12

DESCRIPTION

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
30       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
45       debuild  also  reads  the  devscripts  configuration files as described
46       below.  This allows default options to be given.
47

Directory name checking

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
60       DEVSCRIPTS_CHECK_DIRNAME_LEVEL can take the following values:
61
62       0      Never check the directory name.
63
64       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
68       2      Always check the directory name.
69
70       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

ENVIRONMENT VARIABLES

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
92       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
103       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
107       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

SUPERUSER REQUIREMENTS

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
121       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
126       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

HOOKS

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
147       dpkg-buildpackage-hook
148              Run  before dpkg-buildpackage begins by calling dpkg-checkbuild‐
149              deps.
150
151              Hook is run inside the unpacked source.
152
153              Corresponds to dpkg's init hook.
154
155       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
160              Hook is run inside the unpacked source.
161
162              Corresponds to dpkg's preclean hook.
163
164       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
169              Hook is run inside the unpacked source.
170
171              Corresponds to dpkg's source hook.
172
173       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
178              Hook is run inside the unpacked source.
179
180              Corresponds to dpkg's build hook.
181
182       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
186              Hook is run inside the unpacked source.
187
188              Corresponds to dpkg's binary hook.
189
190       dpkg-genchanges-hook
191              Run  after  the binary package is built and before calling dpkg-
192              genchanges.
193
194              Hook is run inside the unpacked source.
195
196              Corresponds to dpkg's changes hook.
197
198       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
203              Hook is run inside the unpacked source.
204
205              Corresponds to dpkg's postclean hook.
206
207       lintian-hook
208              Run (once) before calling lintian.  (Run  even  if  we  are  not
209              calling lintian.)
210
211              Hook is run from parent directory of unpacked source.
212
213              Corresponds to dpkg's check hook.
214
215       signing-hook
216              Run  after calling lintian before any signing takes place.  (Run
217              even if we are not signing anything.)
218
219              Hook is run from parent directory of unpacked source.
220
221              Corresponds to dpkg's sign hook, but is run by debuild.
222
223       post-dpkg-buildpackage-hook
224              Run after everything has finished.
225
226              Hook is run from parent directory of unpacked source.
227
228              Corresponds to dpkg's done hook, but is run by debuild.
229
230       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
245       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

OPTIONS

250       For details, see above.
251
252       --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
256       --rootcmd=gain-root-command, -rgain-root-command
257              Command to gain root (or fake root) privileges.
258
259       --preserve-env
260              Do not clean the environment, except for PATH.
261
262       --preserve-envvar=var, -evar
263              Do not clean the var variable from the environment.
264
265              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
269       --set-envvar=var=value, -evar=value
270              Set the environment variable var to value and do not  remove  it
271              from the environment.
272
273       --prepend-path=value
274              Once the normalized PATH has been set, prepend value to it.
275
276       --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
281       --no-lintian
282              Do not run lintian after dpkg-buildpackage.
283
284       --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
289       --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
295       --username username
296              When signing, use debrsign instead of debsign.  username  speci‐
297              fies the credentials to be used.
298
299       --foo-hook=hook
300              Set  a  hook  as described above.  If hook is blank, this unsets
301              the hook.
302
303       --clear-hooks
304              Clears all hooks.  They may be reinstated by later command  line
305              options.
306
307       --check-dirname-level N
308              See the above section Directory name checking for an explanation
309              of this option.
310
311       --check-dirname-regex regex
312              See the above section Directory name checking for an explanation
313              of this option.
314
315       -d     Do not run dpkg-checkbuilddeps to check build dependencies.
316
317       -D     Run dpkg-checkbuilddeps to check build dependencies.
318

CONFIGURATION VARIABLES

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
328       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
332       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
337       DEBUILD_SET_ENVVAR_var=value
338              This corresponds to --set-envvar=var=value.
339
340       DEBUILD_PREPEND_PATH
341              This corresponds to --prepend-path.
342
343       DEBUILD_ROOTCMD
344              Setting this variable to prog is the equivalent of -rprog.
345
346       DEBUILD_TGZ_CHECK
347              Setting this variable to no is the same  as  the  --no-tgz-check
348              command line option.
349
350       DEBUILD_SIGNING_USERNAME
351              Setting  this  variable is the same as using the --username com‐
352              mand line option.
353
354       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
363              DEBUILD_DPKG_BUILDPACKAGE_OPTS="-k'Julian Gilbey <jdg@debian.org>' -sa"
364
365              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
369              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
374       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
378       DEBUILD_LINTIAN
379              Should we run lintian?  If this is set to no, then lintian  will
380              not be run.
381
382       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
388       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

EXAMPLES

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
399       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
402              debuild -i -us -uc -b
403
404       Change the -b to -S to build only a source package.
405
406       An example using lintian to check the resulting  packages  and  passing
407       options to it:
408
409              debuild --lintian-opts -i
410
411       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
418       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
421              dpkg-source -x foobar_1.0-1.dsc
422              cd foobar-1.0
423              debuild -k0x12345678
424
425       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

SEE ALSO

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

AUTHOR

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>.
440
441
442
443DEBIAN                         Debian Utilities                     DEBUILD(1)
Impressum