=back
+=head1 BUILD SYSTEM OPTIONS
+
+The following command line options are supported by all of the dh_auto_*
+debhelper programs. These programs support a variety of build systems,
+and normally heuristically determine which to use, and how to use them.
+You can use these command line options to override the default behavior.
+
+=over 4
+
+=item B<-S>I<buildsystem>, B<--buildsystem=>I<buildsystem>
+
+Force use of the specified I<buildsystem>, instead of trying to auto-select
+one which might be applicable for the package.
+
+=item B<-D>I<directory>, B<--sourcedirectory=>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.
+
+=item B<-B>[I<directory>], B<--builddirectory>=[I<directory>]
+
+Enable out of source building and use the specified I<directory> as the build
+directory. If I<directory> parameter is omitted, a default build directory
+will chosen.
+
+If this option is not specified, building will be done in source by default
+unless the build system requires or 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 build system 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 the same as the source directory path.
+
+=item B<--list>, B<-l>
+
+List all build systems supported by debhelper on this system. The list
+includes both default and third party build systems (marked as such). Also
+shows which build system would be automatically selected, 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.
+
+=back
+
=head1 NOTES
=head2 Multiple binary package support
=head1 SYNOPSIS
-B<dh_auto_build> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_build> [S<I<build system options>>] [S<I<debhelper options>>] [S<B<--> I<params>>]
=head1 DESCRIPTION
-dh_auto_build is a debhelper program that tries to automatically
-build a package. If a Makefile is found, this is done by running make (or
-MAKE, if the environment variable is set).
-If there's a setup.py, or Build.PL, it is run to build the package.
+dh_auto_build is a debhelper program that tries to automatically build a
+package. It does so by running the appropriate command for the build system
+it detects the package uses. For example, if a Makefile is found, this is
+done by running make (or MAKE, if the environment variable is set). If
+there's a setup.py, or Build.PL, it is run to build the package.
This is intended to work for about 90% of packages. If it doesn't work,
you're encouraged to skip using dh_auto_build at all, and just run the
=head1 OPTIONS
+See L<debhelper(7)/BUILD SYSTEM OPTIONS> for a list of common build
+system selection and control options.
+
=over 4
=item B<--> I<params>
=head1 SYNOPSIS
-B<dh_auto_clean> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_clean> [S<I<build system options>>] [S<I<debhelper options>>] [S<B<--> I<params>>]
=head1 DESCRIPTION
dh_auto_clean is a debhelper program that tries to automatically clean up
-after a package build. If there's a Makefile and it contains a "distclean",
-"realclean", or "clean" target, then this is done by running make (or MAKE,
-if the environment variable is set). If there is a setup.py or Build.PL, it
-is run to clean the package.
+after a package build. It does so by running the appropriate command for
+the build system it detects the package uses. For example, if there's a
+Makefile and it contains a "distclean", "realclean", or "clean" target,
+then this is done by running make (or MAKE, if the environment variable is
+set). If there is a setup.py or Build.PL, it is run to clean the package.
This is intended to work for about 90% of packages. If it doesn't work, or
tries to use the wrong clean target, you're encouraged to skip using
=head1 OPTIONS
+See L<debhelper(7)/BUILD SYSTEM OPTIONS> for a list of common build
+system selection and control options.
+
=over 4
=item B<--> I<params>
=head1 SYNOPSIS
-B<dh_auto_configure> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_configure> [S<I<build system options>>] [S<I<debhelper options>>] [S<B<--> I<params>>]
=head1 DESCRIPTION
dh_auto_configure is a debhelper program that tries to automatically
-configure a package prior to building. It looks for and runs a ./configure
-script, Makefile.PL, Build.PL, or cmake. A standard set of parameters is
-determined and passed to the program that is run. If no program to run is
-found, dh_auto_configure will exit without doing anything.
+configure a package prior to building. It does so by running the
+appropriate command for the build system it detects the package uses.
+For example, it looks for and runs a ./configure script, Makefile.PL,
+Build.PL, or cmake. A standard set of parameters is determined and passed
+to the program that is run. Some build systems, such as make, do not
+need a configure step; for these dh_auto_configure will exit without
+doing anything.
This is intended to work for about 90% of packages. If it doesn't work,
you're encouraged to skip using dh_auto_configure at all, and just run
=over 4
+See L<debhelper(7)/BUILD SYSTEM OPTIONS> for a list of common build
+system selection and control options.
+
=item B<--> I<params>
Pass "params" to the program that is run, after the standard
=head1 SYNOPSIS
-B<dh_auto_install> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_install> [S<I<build system options>>] [S<I<debhelper options>>] [S<B<--> I<params>>]
=head1 DESCRIPTION
dh_auto_install is a debhelper program that tries to automatically install
-built files. If there's a Makefile and it contains a "install" target,
-then this is done by running make (or MAKE, if the environment variable is
-set). If there is a setup.py or Build.PL, it is used.
+built files. It does so by running the appropriate command for the build
+system it detects the package uses. For example, if there's a Makefile and
+it contains a "install" target, then this is done by running make (or MAKE,
+if the environment variable is set). If there is a setup.py or Build.PL,
+it is used.
The files are installed into debian/<package>/ if there is only one binary
package. In the multiple binary package case, the files are instead
=over 4
+See L<debhelper(7)/BUILD SYSTEM OPTIONS> for a list of common build
+system selection and control options.
+
=item B<--> I<params>
Pass "params" to the program that is run. These can be used to supplement
=head1 SYNOPSIS
-B<dh_auto_test> [S<I<debhelper options>>] [S<B<--> I<params>>]
+B<dh_auto_test> [S<I<build system options>>] [S<I<debhelper options>>] [S<B<--> I<params>>]
=head1 DESCRIPTION
dh_auto_test is a debhelper program that tries to automatically run a
-package's test suite. If there's a Makefile and it contains a "test"
-or "check" target, then this is done by running make (or MAKE, if the
-environment variable is set). If the test suite fails, the command will
-exit nonzero. If there's no test suite, it will exit zero without doing
-anything.
+package's test suite. It does so by running the appropriate command for the
+build system it detects the package uses. For example, if there's a
+Makefile and it contains a "test" or "check" target, then this is done by
+running make (or MAKE, if the environment variable is set). If the test
+suite fails, the command will exit nonzero. If there's no test suite, it
+will exit zero without doing anything.
This is intended to work for about 90% of packages with a test suite. If it
doesn't work, you're encouraged to skip using dh_auto_test at all, and
=head1 OPTIONS
+See L<debhelper(7)/BUILD SYSTEM OPTIONS> for a list of common build
+system selection and control options.
+
=over 4
=item B<--> I<params>
The debian/clean file can list other files to be removed.
It does not run "make clean" to clean up after the build process. Use
-L<dh_auto_clean(1)> to do that.
+L<dh_auto_clean(1)> to do things like that.
dh_clean (or "dh clean") should be the last debhelper command run in the
clean target in debian/rules.