Merge branch 'master' into buildsystems

[debhelper.git] / debhelper.pod

diff --git a/debhelper.pod b/debhelper.pod
index 2cc4f38f03c5d884f18ad69a7d508e5c80bad16b..cea528367e6c673bab743080fd4002567f540a92 100644 (file)
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -62,9 +62,10 @@ debian/control, debhelper will use debian/foo if no debian/package.foo
 file can be found.
 
 In some rare cases, you may want to have different versions of these files
-for different architectures. If files named debian/package.foo.arch
-exist, where "arch" is the same as the output of 
-"dpkg-architecture -qDEB_HOST_ARCH",
+for different architectures or OSes. If files named debian/package.foo.ARCH
+or debian/package.foo.OS exist, where "ARCH" and "OS" are the same as the
+output of  "dpkg-architecture -qDEB_HOST_ARCH" /
+"dpkg-architecture -qDEB_HOST_ARCH_OS",
 then they will be used in preference to other, more general files.
 
 In many cases, these config files are used to specify various types of
@@ -118,6 +119,14 @@ are not architecture independent.
 Do not act on the specified package even if an -a, -i, or -p option lists
 the package as one that should be acted on.
 
+=item B<--remaining-packages>
+
+Do not act on the packages which have already been acted on by this debhelper
+command earlier (i.e. if the command is present in the package debhelper log).
+For example, if you need to call the command with special options only for a
+couple of binary packages, pass this option to the last call of the command to
+process the rest of packages with default settings. 
+
 =item B<--ignore=>I<file>
 
 Ignore the specified file. This can be used if debian/ contains a debhelper
@@ -165,6 +174,50 @@ 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.
+
+=back
+
 =head1 NOTES
 
 =head2 Multiple binary package support
@@ -333,6 +386,8 @@ dh_link will correct existing links to conform with policy.
 
 =back
 
+This mode is deprecated.
+
 =item V5
 
 Changes from V4 are:
@@ -366,8 +421,8 @@ Changes from V5 are:
 
 =item -
 
-Commands that generate maintainer script fragements will order the
-fragements in reverse order for the prerm and postrm scripts.
+Commands that generate maintainer script fragments will order the
+fragments in reverse order for the prerm and postrm scripts.
 
 =item -
 
@@ -384,7 +439,7 @@ DH_ALWAYS_EXCLUDE, if it was set to a list of things to exclude, such as
 =item -
 
 dh_installman allows overwriting existing man pages in the package build
-directory. In previous compatability levels it silently refuses to do this.
+directory. In previous compatibility levels it silently refuses to do this.
 
 =back
 
@@ -398,10 +453,10 @@ Changes from V6 are:
 
 =item -
 
-dh_install, if --sourcedir is not specified, will first look for files in
-debian/tmp, and then will look in the current directory. This allows
-dh_install to interoperate with dh_auto_install without needing any special
-parameters.
+dh_install, will fall back to looking for files in debian/tmp if it doesn't
+find them in the current directory (or wherever you tell it look using
+--sourcedir). This allows dh_install to interoperate with dh_auto_install,
+which installs to debian/tmp, without needing any special parameters.
 
 =item -
 
@@ -477,10 +532,13 @@ Set to 1 to enable no-act mode.
 =item DH_OPTIONS
 
 Anything in this variable will be prepended to the command line arguments
-of all debhelper commands. This is useful in some situations, for example,
-if you need to pass -p to all debhelper commands that will be run. One good
-way to set DH_OPTIONS is by using "Target-specific Variable Values" in your
-debian/rules file. See the make documentation for details on doing this.
+of all debhelper commands. Command-specific options will be ignored by 
+commands that do not support them. 
+
+This is useful in some situations, for example, if you need to pass -p to
+all debhelper commands that will be run. One good way to set DH_OPTIONS is
+by using "Target-specific Variable Values" in your debian/rules file. See
+the make documentation for details on doing this.
 
 =item DH_ALWAYS_EXCLUDE