summaryrefslogtreecommitdiff
path: root/dh_auto.pod
diff options
context:
space:
mode:
Diffstat (limited to 'dh_auto.pod')
-rw-r--r--dh_auto.pod228
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>