path: root/dh_auto.pod

=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>