From: Joey Hess Date: Sun, 28 Jun 2009 19:40:15 +0000 (-0400) Subject: minimal build system option documentation X-Git-Tag: 7.3.0~28 X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=93c1062bc3ee340fcd7318e91fe9758d86b760f3;p=debhelper.git minimal build system option documentation --- diff --git a/debhelper.pod b/debhelper.pod index 388453c..40147a5 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, B<--buildsystem=>I + +Force use of the specified I, instead of trying to auto-select +one which might be applicable for the package. + +=item B<-D>I, B<--sourcedirectory=>I + +Assume that the original package source tree is at the specified +I rather than the top level directory of the Debian +source package tree. + +=item B<-B>[I], B<--builddirectory>=[I] + +Enable out of source building and use the specified I as the build +directory. If I 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 56b9b5f..250c7d9 100755 --- a/dh_auto_build +++ b/dh_auto_build @@ -11,14 +11,15 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S I>] +B [S>] [S>] [S I>] =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 for a list of common build +system selection and control options. + =over 4 =item B<--> I diff --git a/dh_auto_clean b/dh_auto_clean index 1b7d46c..8603b11 100755 --- a/dh_auto_clean +++ b/dh_auto_clean @@ -11,15 +11,16 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S I>] +B [S>] [S>] [S I>] =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 for a list of common build +system selection and control options. + =over 4 =item B<--> I diff --git a/dh_auto_configure b/dh_auto_configure index 34d6298..4a8c28c 100755 --- a/dh_auto_configure +++ b/dh_auto_configure @@ -11,15 +11,18 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S I>] +B [S>] [S>] [S I>] =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 for a list of common build +system selection and control options. + =item B<--> I Pass "params" to the program that is run, after the standard diff --git a/dh_auto_install b/dh_auto_install index db2c6e9..4464702 100755 --- a/dh_auto_install +++ b/dh_auto_install @@ -13,14 +13,16 @@ use Cwd; =head1 SYNOPSIS -B [S>] [S I>] +B [S>] [S>] [S I>] =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// 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 for a list of common build +system selection and control options. + =item B<--> I 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 e68bf09..6caf393 100755 --- a/dh_auto_test +++ b/dh_auto_test @@ -11,16 +11,17 @@ use Debian::Debhelper::Dh_Buildsystems; =head1 SYNOPSIS -B [S>] [S I>] +B [S>] [S>] [S I>] =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 for a list of common build +system selection and control options. + =over 4 =item B<--> I diff --git a/dh_clean b/dh_clean index 47019fc..1213f6c 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 to do that. +L to do things like that. dh_clean (or "dh clean") should be the last debhelper command run in the clean target in debian/rules.