diff options
Diffstat (limited to 'dh_auto.pod')
-rw-r--r-- | dh_auto.pod | 228 |
1 files changed, 228 insertions, 0 deletions
diff --git a/dh_auto.pod b/dh_auto.pod new file mode 100644 index 00000000..6eb244fb --- /dev/null +++ b/dh_auto.pod @@ -0,0 +1,228 @@ +=head1 NAME + +dh_auto - debhelper based package source building suite + +=head1 SYNOPTIS + +B<dh_auto_*> [B<--buildsystem=>I<buildsystem>] [B<--sourcedirectory=>I<srcdir>] [B<--builddirectory>[=I<builddir>]] + +B<dh_auto_*> B<--list> [B<-S>I<buildsystem>] [B<-D>I<srcdir>] [B<-B>[I<builddir>]] + +B<dh_auto_*> B<--help-buildsystem> [B<-S>I<buildsystem>] [B<-D>I<srcdir>] [B<-B>[I<builddir>]] + +=head1 DESCRIPTION + +dh_auto is a family of debhelper programs that are responsible for managing +build process of the package sources. dh_auto takes a burden of identifying and +configuring package build system with a standard set of options that a typical +Debian package needs. However, it is also flexible enough to allow +customization of the build process in various ways. Due to good defaults, it +should be able to handle 90% of packages even without any additional arguments +passed to the dh_auto programs. Therefore, dh_auto is one of the main driving +forces behind the L<dh(1)> command sequencer. Similarly, dh_auto programs can +be easily (either fully or partially) integrated into traditional Debian +packaging. + +One of the key dh_auto features is that it wraps around all common source build +systems and exposes their common features via well-defined command line +interface of the dh_auto programs. dh_auto is designed that each type of source +build system is handled by its corresponding I<debhelper build system> which +translates dh_auto options into the source build system specific details. +Therefore, dh_auto is capable to handle e.g. out of source tree building +transparently. + +The build process is split into 5 I<building steps>: configure, build, test, +install and clean. Each step is managed by the respective dh_auto_$step +program. Each program accepts a set of shared dh_auto options, step specific +options (if any) and arbitrary number of extra arguments which are additionally +passed to the underlying build system command being executed. Whatever is +executed under the hood depends on the selected debhelper build system, +building step (i.e. dh_auto program) and dh_auto options in effect. + +=head1 DH_AUTO PROGRAMS + +=over 2 + +#DH_AUTO LIST# + +=back + +=head1 FEATURES + +=over 2 + +=item I<Build system auto-selection> + +dh_auto examines package source and/or build directories at each building step +looking for typical indications of the source build systems it supports. If the +build system is recognized, its corresponding building step commands are +executed. If more than one debhelper build system indicates to match the source +build system, only the first one is selected. If the build system isn't +recognized, dh_auto program silently succeeds. dh_auto programs may fail only +if wrong debhelper build system gets selected and/or source build system +commands fail or cannot be executed. + +The auto-selection process implies that a different but compatible debhelper +build system may be auto-selected at each building step. For example, GNU +Autoconf is just a configure layer on top of the simple Makefile build system. + +=item I<Manual build system selection> + +In addition to the build system auto-selection, dh_auto offers a way for a user +to specify which debhelper build system to assume for the package. In such a +case, auto-selection is skipped entirely and no prior checks are made before +executing commands of the specified build system. Obviously, if a wrong build +system was specified and/or source build system commands failed or could not be +executed, the dh_auto program would fail too. + +Manual build system selection could be useful if package sources came with more +than one build system, auto-selection fails/gives wrong results due its +limitations or you want to use a third party debhelper build system (provided +by an external package (see below)). + +=item I<Source tree switching> + +Typically, the top directory of the package sources is where the debianization +directory (debian/) lives. However, sometimes the whole original source tree +might be somewhere in the subdirectory or a single Debian source package might +actually contain multiple original source packages with their contents being in +the separate subdirectories. dh_auto handles such cases by letting the user to +specify a path to the source directory. All dh_auto programs regardless of the +build system selected support source directory switching. + +=item I<Out of source tree building> + +Throughout the build process of the most packages, lots of temporary files are +generated by their source build systems. Since they are of no use when binary +packages are built, it is a task of L<dh_auto_clean(1)> to clean them up. If +temporary files are generated in the same directories where source files are, +it is referred as "in source building" in this documentation. However, some +build systems support the concept of "out of source tree" building when all +temporary files are generated in the arbitrary build directory avoiding +extensive pollution of the source tree. dh_auto allows to specify a path to the +build directory and then it will do out of source tree building in it if the +source build system supports this feature. + +In source building is a default mode and it is supported by most debhelper +build systems. However, some source build systems do not support in source +building or highly recommend out of source tree building. In this case, dh_auto +follows the recommendation and might default to the out of source tree building +even if the build directory was not explicitly specified. However, if the build +system does not support out of source tree building, it is an error to specify +the build directory. + +=item I<Third party debhelper build systems> + +It is very easy to write a third party debhelper build system class and ship it +in the external package. The only limitation is that support for it can only be +enabled manually (via "Manual build system selection"). Their auto-selection is +not allowed in order to keep the process stable under various system +configurations (i.e. when different sets of third party debhelper build systems +are installed). However, the user can always discover all default and third +party debhelper build systems supported on the system by passing the L<--list> +option to any dh_auto program. + +=back + +Read section L</"DH_AUTO SHARED OPTIONS"> for more details how to enable the +features listed above. + +=head1 SUPPORTED BUILD SYSTEMS + +dh_auto provides support for the most popular build systems out of the box +(listed below). See section L</"DEBHELPER BUILD SYSTEM DETAILS"> for more +information how each build system is auto-selected and what commands are +executed to complete each building step. To get information about a third party +debhelper build system installed on your system, use I<--help-buildsystem> +option. + +#SUPPORTED BUILD SYSTEMS# + +=head1 #SUPPORTED BUILD SYSTEMS INTRO FOR DH_AUTO PROGRAMS + +Below you will find a list of the debhelper build systems that are shipped with +debhelper itself along with their details concerning this building step. They +are listed in the order of auto-selection preference. Consult +L<dh_auto_$buildsystem(7)> or L</"DEBHELPER BUILD SYSTEM DETAILS"> section of +L<dh_auto(7)>, or use L<--help--buildsystem> option for a more complete +reference about each build system. + +=head1 DH_AUTO SHARED OPTIONS + +=over 4 + +=item B<--buildsystem=>I<buildsystem>, B<-S>I<buildsystem> + +Select the specified debhelper I<buildsystem> instead of trying to auto-select +one which might be applicable for the package. I<buildsystem> specific commands +will be executed to complete a building step without any prior checks. This +option is also the only way to select a third party debhelper build system. + +=item B<--sourcedirectory>=I<directory>, B<-D>I<directory> + +Assume that the original package source tree is at the specified I<directory> +rather than the top level directory of the Debian source package tree (C<.>). +I<directory> path is assumed to be relative to the top level directory (where +debian/ is) and must exist. + +=item B<--builddirectory>=[I<directory>], B<-B>[I<directory>] + +Enable out of source building and use the specified I<directory> as the build +directory. If specified, I<directory> must be relative to the top level +directory of the Debian source package tree and generally does not need to +exist before the build process is started. If I<directory> parameter is +omitted, default build directory will be used. It is S<C<obj-`dpkg_architecture +-qDEB_BUILD_GNU_TYPE`>> by default but any debhelper build system can choose +another value (see documentation of the debhelper build systems). + +If this option is not specified, building will be done in source by default +unless the selected build system enforces/prefers out of source tree building. +In such a case, the default build directory will be used even if +L<--builddirectory> is not specified. If the selected build system just prefers +out of source tree building but still allows in source building, the latter can +be re-enabled by passing a build directory path that is equal to the source +directory path. + +=item B<--list>, B<-l> + +List all debhelper build systems available on this system and exit. The list +includes both default (listed first in the auto-selection order) and third +party build systems (clearly marked as such). The list is concluded with the +information about which build system would be auto-selected to complete the +building step or which one is manually specified with the I<--buildsystem> +option. + +=item B<--help-buildsystem> + +Print detailed help about a build system which would be auto-selected or which +is manually specified with the L<--buildsystem> option. Exit immediately +afterwards. + +=back + +=head1 DEBHELPER BUILD SYSTEM DETAILS + +This section provides more information about debhelper build systems supported +by default. They are listed in the order of auto-selection preference. The +first build system that matches auto-selection criteria is always selected and +the following ones are not even considered. Auto-selection conditions might +differ at each building step even for the same debhelper build system. + +#BUILD SYSTEM DETAILS# + +=head1 SEE ALSO + +L<debhelper(7)> + +=over 2 + +=item B<Default debhelper build systems> + +#BUILD SYSTEM MAN LIST# + +=back + +=head1 AUTHORS + + Joey Hess <joeyh@debian.org> + Modestas Vainius <modestas@vainius.eu> |