minimal build system option documentation

7 files changed, 98 insertions, 26 deletions

diff --git a/debhelper.pod b/debhelper.pod
index 388453c3..40147a50 100644
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -174,6 +174,55 @@ in ALL packages acted on, not just the first.
 
 =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
diff --git a/dh_auto_build b/dh_auto_build
index 56b9b5f0..250c7d93 100755
--- a/dh_auto_build
+++ b/dh_auto_build
@@ -11,14 +11,15 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =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
@@ -26,6 +27,9 @@ build process manually.
 
 =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>
diff --git a/dh_auto_clean b/dh_auto_clean
index 1b7d46cd..8603b111 100755
--- a/dh_auto_clean
+++ b/dh_auto_clean
@@ -11,15 +11,16 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =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
@@ -27,6 +28,9 @@ dh_auto_clean at all, and just run make clean manually.
 
 =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>
diff --git a/dh_auto_configure b/dh_auto_configure
index 34d6298a..4a8c28c6 100755
--- a/dh_auto_configure
+++ b/dh_auto_configure
@@ -11,15 +11,18 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =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
@@ -29,6 +32,9 @@ 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
diff --git a/dh_auto_install b/dh_auto_install
index db2c6e90..44647027 100755
--- a/dh_auto_install
+++ b/dh_auto_install
@@ -13,14 +13,16 @@ use Cwd;
 
 =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
@@ -40,6 +42,9 @@ dh_auto_install at all, and just run make install manually.
 
 =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
diff --git a/dh_auto_test b/dh_auto_test
index e68bf09a..6caf393e 100755
--- a/dh_auto_test
+++ b/dh_auto_test
@@ -11,16 +11,17 @@ use Debian::Debhelper::Dh_Buildsystems;
 
 =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
@@ -28,6 +29,9 @@ just run the test suite manually.
 
 =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>
diff --git a/dh_clean b/dh_clean
index 47019fcd..1213f6ca 100755
--- a/dh_clean
+++ b/dh_clean
@@ -25,7 +25,7 @@ debian diff:
 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.