dh_auto.pod

   1 =head1 NAME
   2
   3 dh_auto - debhelper based package source building suite
   4
   5 =head1 SYNOPTIS
   6
   7 B<dh_auto_*> [B<--buildsystem=>I<buildsystem>] [B<--sourcedirectory=>I<srcdir>] [B<--builddirectory>[=I<builddir>]]
   8
   9 B<dh_auto_*> B<--list> [B<-S>I<buildsystem>] [B<-D>I<srcdir>] [B<-B>[I<builddir>]]
  10
  11 B<dh_auto_*> B<--help-buildsystem> [B<-S>I<buildsystem>] [B<-D>I<srcdir>] [B<-B>[I<builddir>]]
  12
  13 =head1 DESCRIPTION
  14
  15 dh_auto is a family of debhelper programs that are responsible for managing
  16 build process of the package sources. dh_auto takes a burden of identifying and
  17 configuring package build system with a standard set of options that a typical
  18 Debian package needs. However, it is also flexible enough to allow
  19 customization of the build process in various ways. Due to good defaults, it
  20 should be able to handle 90% of packages even without any additional arguments
  21 passed to the dh_auto programs. Therefore, dh_auto is one of the main driving
  22 forces behind the L<dh(1)> command sequencer. Similarly, dh_auto programs can
  23 be easily (either fully or partially) integrated into traditional Debian
  24 packaging.
  25
  26 One of the key dh_auto features is that it wraps around all common source build
  27 systems and exposes their common features via well-defined command line
  28 interface of the dh_auto programs. dh_auto is designed that each type of source
  29 build system is handled by its corresponding I<debhelper build system> which
  30 translates dh_auto options into the source build system specific details.
  31 Therefore, dh_auto is capable to handle e.g. out of source tree building
  32 transparently.
  33
  34 The build process is split into 5 I<building steps>: configure, build, test,
  35 install and clean. Each step is managed by the respective dh_auto_$step
  36 program. Each program accepts a set of shared dh_auto options, step specific
  37 options (if any) and arbitrary number of extra arguments which are additionally
  38 passed to the underlying build system command being executed. Whatever is
  39 executed under the hood depends on the selected debhelper build system,
  40 building step (i.e.  dh_auto program) and dh_auto options in effect.
  41
  42 =head1 DH_AUTO PROGRAMS
  43
  44 =over 2
  45
  46 #DH_AUTO LIST#
  47
  48 =back
  49
  50 =head1 FEATURES
  51
  52 =over 2
  53
  54 =item I<Build system auto-selection>
  55
  56 dh_auto examines package source and/or build directories at each building step
  57 looking for typical indications of the source build systems it supports. If the
  58 build system is recognized, its corresponding building step commands are
  59 executed. If more than one debhelper build system indicates to match the source
  60 build system, only the first one is selected. If the build system isn't
  61 recognized, dh_auto program silently succeeds. dh_auto programs may fail only
  62 if wrong debhelper build system gets selected and/or source build system
  63 commands fail or cannot be executed.
  64
  65 The auto-selection process implies that a different but compatible debhelper
  66 build system may be auto-selected at each building step. For example, GNU
  67 Autoconf is just a configure layer on top of the simple Makefile build system.
  68
  69 =item I<Manual build system selection>
  70
  71 In addition to the build system auto-selection, dh_auto offers a way for a user
  72 to specify which debhelper build system to assume for the package. In such a
  73 case, auto-selection is skipped entirely and no prior checks are made before
  74 executing commands of the specified build system. Obviously, if a wrong build
  75 system was specified and/or source build system commands failed or could not be
  76 executed, the dh_auto program would fail too.
  77
  78 Manual build system selection could be useful if package sources came with more
  79 than one build system, auto-selection fails/gives wrong results due its
  80 limitations or you want to use a third party debhelper build system (provided
  81 by an external package (see below)).
  82
  83 =item I<Source tree switching>
  84
  85 Typically, the top directory of the package sources is where the debianization
  86 directory (debian/) lives. However, sometimes the whole original source tree
  87 might be somewhere in the subdirectory or a single Debian source package might
  88 actually contain multiple original source packages with their contents being in
  89 the separate subdirectories. dh_auto handles such cases by letting the user to
  90 specify a path to the source directory. All dh_auto programs regardless of the
  91 build system selected support source directory switching.
  92
  93 =item I<Out of source tree building>
  94
  95 Throughout the build process of the most packages, lots of temporary files are
  96 generated by their source build systems. Since they are of no use when binary
  97 packages are built, it is a task of L<dh_auto_clean(1)> to clean them up.  If
  98 temporary files are generated in the same directories where source files are,
  99 it is referred as "in source building" in this documentation. However, some
 100 build systems support the concept of "out of source tree" building when all
 101 temporary files are generated in the arbitrary build directory avoiding
 102 extensive pollution of the source tree. dh_auto allows to specify a path to the
 103 build directory and then it will do out of source tree building in it if the
 104 source build system supports this feature.
 105
 106 In source building is a default mode and it is supported by most debhelper
 107 build systems. However, some source build systems do not support in source
 108 building or highly recommend out of source tree building. In this case, dh_auto
 109 follows the recommendation and might default to the out of source tree building
 110 even if the build directory was not explicitly specified. However, if the build
 111 system does not support out of source tree building, it is an error to specify
 112 the build directory.
 113
 114 =item I<Third party debhelper build systems>
 115
 116 It is very easy to write a third party debhelper build system class and ship it
 117 in the external package. The only limitation is that support for it can only be
 118 enabled manually (via "Manual build system selection"). Their auto-selection is
 119 not allowed in order to keep the process stable under various system
 120 configurations (i.e. when different sets of third party debhelper build systems
 121 are installed). However, the user can always discover all standard and third
 122 party debhelper build systems supported on the system by passing the L<--list>
 123 option to any dh_auto program.
 124
 125 =back
 126
 127 Read section L</"DH_AUTO SHARED OPTIONS"> for more details how to enable the
 128 features listed above.
 129
 130 =head1 SUPPORTED BUILD SYSTEMS
 131
 132 dh_auto provides support for the most popular build systems out of the box
 133 (listed below). See section L</"DEBHELPER BUILD SYSTEM DETAILS"> for more
 134 information how each build system is auto-selected and what commands are
 135 executed to complete each building step. To get information about a third party
 136 debhelper build system installed on your system, use I<--help-buildsystem>
 137 option.
 138
 139 #SUPPORTED BUILD SYSTEMS#
 140
 141 =head1 #SUPPORTED BUILD SYSTEMS INTRO FOR DH_AUTO PROGRAMS
 142
 143 Below you will find a list of the debhelper build systems that are shipped with
 144 debhelper itself along with their details concerning this building step. They
 145 are listed in the order of auto-selection preference. Consult
 146 L<dh_auto_$buildsystem(7)> or L</"DEBHELPER BUILD SYSTEM DETAILS"> section of
 147 L<dh_auto(7)>, or use L<--help--buildsystem> option for a more complete
 148 reference about each build system.
 149
 150 =head1 DH_AUTO SHARED OPTIONS
 151
 152 =over 4
 153
 154 =item B<--buildsystem=>I<buildsystem>, B<-S>I<buildsystem>
 155
 156 Select the specified debhelper I<buildsystem> instead of trying to auto-select
 157 one which might be applicable for the package. I<buildsystem> specific commands
 158 will be executed to complete a building step without any prior checks. This
 159 option is also the only way to select a third party debhelper build system.
 160
 161 =item B<--sourcedirectory>=I<directory>, B<-D>I<directory>
 162
 163 Assume that the original package source tree is at the specified I<directory>
 164 rather than the top level directory of the Debian source package tree (C<.>).
 165 I<directory> path is assumed to be relative to the top level directory (where
 166 debian/ is) and must exist.
 167
 168 =item B<--builddirectory>=[I<directory>], B<-B>[I<directory>]
 169
 170 Enable out of source building and use the specified I<directory> as the build
 171 directory. If specified, I<directory> must be relative to the top level
 172 directory of the Debian source package tree and generally does not need to
 173 exist before the build process is started. If I<directory> parameter is
 174 omitted, default build directory will be used. It is S<C<obj-`dpkg_architecture
 175 -qDEB_BUILD_GNU_TYPE`>> by default but any debhelper build system can choose
 176 another value (see documentation of the debhelper build systems).
 177
 178 If this option is not specified, building will be done in source by default
 179 unless the selected build system enforces/prefers out of source tree building.
 180 In such a case, the default build directory will be used even if
 181 L<--builddirectory> is not specified. If the selected build system just prefers
 182 out of source tree building but still allows in source building, the latter can
 183 be re-enabled by passing a build directory path that is equal to the source
 184 directory path.
 185
 186 =item B<--list>, B<-l>
 187
 188 List all debhelper build systems available on this system and exit. The list
 189 includes both standard (listed first in the auto-selection order) and third
 190 party build systems (clearly marked as such). The list is concluded with the
 191 information about which build system would be auto-selected to complete the
 192 building step or which one is manually specified with the I<--buildsystem>
 193 option.
 194
 195 =item B<--help-buildsystem>
 196
 197 Print detailed help about a build system which would be auto-selected or which
 198 is manually specified with the L<--buildsystem> option. Exit immediately
 199 afterwards.
 200
 201 =back
 202
 203 =head1 DEBHELPER BUILD SYSTEM DETAILS
 204
 205 This section provides more information about debhelper build systems supported
 206 by default. They are listed in the order of auto-selection preference. The
 207 first build system that matches auto-selection criteria is always selected and
 208 the following ones are not even considered. Auto-selection conditions might
 209 differ at each building step even for the same debhelper build system.
 210
 211 #BUILD SYSTEM DETAILS#
 212
 213 =head1 SEE ALSO
 214
 215 L<debhelper(7)>
 216
 217 =over 2
 218
 219 =item B<Standard debhelper build systems>
 220
 221 #BUILD SYSTEM MAN LIST#
 222
 223 =back
 224
 225 =head1 AUTHORS
 226
 227  Joey Hess <joeyh@debian.org>
 228  Modestas Vainius <modestas@vainius.eu>