debuild

DEBUILD(1)                  General Commands Manual                 DEBUILD(1)

NAME
       debuild - build a Debian package

SYNOPSIS
       debuild  [debuild  options] [dpkg-buildpackage options] [--lintian-opts
       lintian options]
       debuild [debuild options] -- binary|binary-arch|binary-indep|clean ...

DESCRIPTION
       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-build-
       package(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 var-
       ious  options  available  for  setting and preserving environment vari-
       ables, 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 param-
       eters  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_BUILDPACK-
       AGE_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.

Directory name checking
       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 par-
       ent 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:

       0      Never check the directory name.

       1      Only check the directory name if we have had to change directory
              in our search for debian/changelog.  This is the default  behav-
              iour.

       2      Always check the directory name.

       The  directory name is checked by testing whether the current directory
       name (as determined by pwd(1)) matches the regex given by the  configu-
       ration  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.

ENVIRONMENT VARIABLES
       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, PGP-
       PATH, 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 --pre-
       serve-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.

SUPERUSER REQUIREMENTS
       debuild  needs  to be run as superuser to function properly.  There are
       three fundamentally different ways to do this.  The first, and  prefer-
       able,  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 pre-
       served across upgrades.

HOOKS
       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:

       dpkg-buildpackage-hook
              Run  before dpkg-buildpackage begins by calling dpkg-checkbuild-
              deps.

              Hook is run inside the unpacked source.

              Corresponds to dpkg's init hook.

       clean-hook
              Run before dpkg-buildpackage runs debian/rules  clean  to  clean
              the  source  tree.   (Run  even if the tree is not being cleaned
              because -nc is used.)

              Hook is run inside the unpacked source.

              Corresponds to dpkg's preclean hook.

       dpkg-source-hook
              Run after cleaning the  tree  and  before  running  dpkg-source.
              (Run  even if dpkg-source is not being called because -b, -B, or
              -A is used.)

              Hook is run inside the unpacked source.

              Corresponds to dpkg's source hook.

       dpkg-build-hook
              Run after dpkg-source and  before  calling  debian/rules  build.
              (Run  even if this is a source-only build, so debian/rules build
              is not being called.)

              Hook is run inside the unpacked source.

              Corresponds to dpkg's build hook.

       dpkg-binary-hook
              Run between debian/rules build and  debian/rules  binary(-arch).
              Run only if a binary package is being built.

              Hook is run inside the unpacked source.

              Corresponds to dpkg's binary hook.

       dpkg-genchanges-hook
              Run  after  the binary package is built and before calling dpkg-
              genchanges.

              Hook is run inside the unpacked source.

              Corresponds to dpkg's changes hook.

       final-clean-hook
              Run after dpkg-genchanges  and  before  the  final  debian/rules
              clean.   (Run  even  if we are not cleaning the tree post-build,
              which is the default.)

              Hook is run inside the unpacked source.

              Corresponds to dpkg's postclean hook.

       lintian-hook
              Run (once) before calling lintian.  (Run  even  if  we  are  not
              calling lintian.)

              Hook is run from parent directory of unpacked source.

              Corresponds to dpkg's check hook.

       signing-hook
              Run  after calling lintian before any signing takes place.  (Run
              even if we are not signing anything.)

              Hook is run from parent directory of unpacked source.

              Corresponds to dpkg's sign hook, but is run by debuild.

       post-dpkg-buildpackage-hook
              Run after everything has finished.

              Hook is run from parent directory of unpacked source.

              Corresponds to dpkg's done hook, but is run by debuild.

       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 com-
       mand  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 per-
       formed 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.

OPTIONS
       For details, see above.

       --no-conf, --noconf
              Do  not  read any configuration files.  This can only be used as
              the first option given on the command-line.

       --rootcmd=gain-root-command, -rgain-root-command
              Command to gain root (or fake root) privileges.

       --preserve-env
              Do not clean the environment, except for PATH.

       --preserve-envvar=var, -evar
              Do not clean the var variable from the environment.

              If var ends in an asterisk ("*") then all variables  with  names
              that  match  the portion of var before the asterisk will be pre-
              served.

       --set-envvar=var=value, -evar=value
              Set the environment variable var to value and do not  remove  it
              from the environment.

       --prepend-path=value
              Once the normalized PATH has been set, prepend value to it.

       --lintian
              Run lintian after dpkg-buildpackage.  This is the default behav-
              iour, and it overrides any configuration file directive  to  the
              contrary.

       --no-lintian
              Do not run lintian after dpkg-buildpackage.

       --no-tgz-check
              Even  if  we're running dpkg-buildpackage and the version number
              has a Debian revision, do not check that the  .orig.tar.gz  file
              or .orig directory exists before starting the build.

       --tgz-check
              If  we're running dpkg-buildpackage and the version number has a
              Debian revision, check  that  the  .orig.tar.gz  file  or  .orig
              directory exists before starting the build.  This is the default
              behaviour.

       --username username
              When signing, use debrsign instead of debsign.  username  speci-
              fies the credentials to be used.

       --foo-hook=hook
              Set  a  hook  as described above.  If hook is blank, this unsets
              the hook.

       --clear-hooks
              Clears all hooks.  They may be reinstated by later command  line
              options.

       --check-dirname-level N
              See the above section Directory name checking for an explanation
              of this option.

       --check-dirname-regex regex
              See the above section Directory name checking for an explanation
              of this option.

       -d     Do not run dpkg-checkbuilddeps to check build dependencies.

       -D     Run dpkg-checkbuilddeps to check build dependencies.

CONFIGURATION VARIABLES
       The  two configuration files /etc/devscripts.conf and ~/.devscripts are
       sourced by a shell in that order to set configuration variables.   Com-
       mand  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_PRESERVE_ENV
              If this is set to yes, then it is the same as the --preserve-env
              command line parameter being used.

       DEBUILD_PRESERVE_ENVVARS
              Which environment variables  to  preserve.   This  should  be  a
              comma-separated  list  of  variables.  This corresponds to using
              possibly multiple --preserve-envvar or -e options.

       DEBUILD_SET_ENVVAR_var=value
              This corresponds to --set-envvar=var=value.

       DEBUILD_PREPEND_PATH
              This corresponds to --prepend-path.

       DEBUILD_ROOTCMD
              Setting this variable to prog is the equivalent of -rprog.

       DEBUILD_TGZ_CHECK
              Setting this variable to no is the same  as  the  --no-tgz-check
              command line option.

       DEBUILD_SIGNING_USERNAME
              Setting  this  variable is the same as using the --username com-
              mand line option.

       DEBUILD_DPKG_BUILDPACKAGE_OPTS
              These are options which should be passed to  the  invocation  of
              dpkg-buildpackage.   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:

              DEBUILD_DPKG_BUILDPACKAGE_OPTS="-k'Julian Gilbey <jdg@debian.org>' -sa"

              which gives precisely two options.   Without  the  extra  single
              quotes,  dpkg-buildpackage would reasonably complain that Gilbey
              is an unrecognised option (it doesn't start with a - sign).

              Also, if this option contains any -r, -d or  -D  options,  these
              will  always  be  taken  account  of by debuild.  Note that a -r
              option  in  this  variable  will   override   the   setting   in
              DEBUILD_ROOTCMD.

       DEBUILD_FOO_HOOK
              The  hook  variable  for the foo hook.  See the section on hooks
              above for more details.  By default, this is empty.

       DEBUILD_LINTIAN
              Should we run lintian?  If this is set to no, then lintian  will
              not be run.

       DEBUILD_LINTIAN_OPTS
              These  are  options  which should be passed to the invocation of
              lintian.  They are given before any  command-line  options,  and
              the   usage   of   this   variable   is  as  described  for  the
              DEBUILD_DPKG_BUILDPACKAGE_OPTS variable.

       DEVSCRIPTS_CHECK_DIRNAME_LEVEL, DEVSCRIPTS_CHECK_DIRNAME_REGEX
              See the above section Directory name checking for an explanation
              of these variables.  Note that these are package-wide configura-
              tion variables, and will therefore affect all devscripts scripts
              which  check  their value, as described in their respective man-
              pages and in devscripts.conf(5).

EXAMPLES
       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  spon-
       sored upload.

SEE ALSO
       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)

AUTHOR
       The  original  debuild program was written by Christoph Lameter <clame-
       ter@debian.org>.  The current version has been written by Julian Gilbey
       <jdg@debian.org>.

DEBIAN                         Debian Utilities                     DEBUILD(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2021 Hurricane Electric. All Rights Reserved.