diff options
Diffstat (limited to 'dh_auto.pod')
| -rw-r--r-- | dh_auto.pod | 228 |
1 files changed, 0 insertions, 228 deletions
diff --git a/dh_auto.pod b/dh_auto.pod deleted file mode 100644 index c8398b5..0000000 --- a/dh_auto.pod +++ /dev/null @@ -1,228 +0,0 @@ -=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 standard 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 standard (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<Standard debhelper build systems> - -#BUILD SYSTEM MAN LIST# - -=back - -=head1 AUTHORS - - Joey Hess <joeyh@debian.org> - Modestas Vainius <modestas@vainius.eu> |