In v8 mode, do not allow directly passing unknown options to debhelper commands....

[debhelper.git] / debhelper.pod

diff --git a/debhelper.pod b/debhelper.pod
index cea528367e6c673bab743080fd4002567f540a92..dae1a1a886a2b1f22d9e2c00aa66fe3e37a0f7b8 100644 (file)
--- a/debhelper.pod
+++ b/debhelper.pod
@@ -28,7 +28,7 @@ package contains a tutorial about making your first package using debhelper.
 
 =head1 DEBHELPER COMMANDS
 
-Here is the complete list of available debhelper commands. See their man
+Here is the list of debhelper commands you can use. See their man
 pages for additional documentation.
 
 =over 4
@@ -37,8 +37,20 @@ pages for additional documentation.
 
 =back
 
+=head2 Deprecated Commands
+
+A few debhelper commands are deprecated and should not be used.
+
+=over 4
+
+#LIST_DEPRECATED#
+
+=back
+
+=head2 Other Commands
+
 If a program's name starts with "dh_", and the program is not on the above
-list, then it is not part of the debhelper package, but it should still
+lists, then it is not part of the debhelper package, but it should still
 work like the other programs described on this page.
 
 =head1 DEBHELPER CONFIG FILES
@@ -93,7 +105,8 @@ will output what it would have done.
 
 =item B<-a>, B<--arch>
 
-Act on all architecture dependent packages.
+Act on architecture dependent packages that should be built for the
+build architecture.
 
 =item B<-i>, B<--indep>
 
@@ -106,13 +119,8 @@ times to make debhelper operate on a given set of packages.
 
 =item B<-s>, B<--same-arch>
 
-This is a smarter version of the -a flag, that is used in some rare
-circumstances. It understands that if the control file lists "Architecture: i386"
-for the package, the package should not be acted on on other architectures. So
-this flag makes the command act on all "Architecture: any" packages, as well
-as on any packages that have the current architecture explicitly specified.
-Contrast to the -a flag, which makes the command work on all packages that
-are not architecture independent.
+This used to be a smarter version of the -a flag, but the -a flag is now
+equally smart.
 
 =item B<-N>I<package>, B<--no-package=>I<package>
 
@@ -148,6 +156,13 @@ This little-used option changes the package which debhelper considers the
 one for which debian/foo files can be used instead of the usual
 debian/package.foo files.
 
+=item B<-O=>I<option|bundle>
+
+This is used by L<dh(1)> when passing user-specified options to all the
+commands it runs. If the command supports the specified option or option
+bundle, it will take effect. If the command does not support the option (or
+any part of an option bundle), it will be ignored.
+
 =back
 
 =head1 COMMON DEBHELPER OPTIONS
@@ -209,6 +224,23 @@ 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<--parallel>
+
+Enable parallel builds if underlying build system supports them.
+The number of parallel jobs is controlled by the
+DEB_BUILD_OPTIONS environment variable (L<Debian Policy, section 4.9.1>) at
+build time. It might also be subject to a build system specific limit.
+
+If this option is not specified, debhelper currently defaults to not
+allowing parallel package builds.
+
+=item B<--max-parallel>I<=maximum>
+
+This option implies L<--parallel> and allows further limiting the number of
+jobs that can be used in a parallel build. If the package build is known to
+only work with certain levels of concurrency, you can set this to the maximum
+level that is known to work, or that you wish to support.
+
 =item B<--list>, B<-l>
 
 List all build systems supported by debhelper on this system. The list
@@ -473,23 +505,27 @@ none is specified.
 
 =back
 
-=back
+=item V8
+
+This mode is still under development. Using it in packages will cause them
+to probably break later.
+
+Changes from V7 are:
+
+=over 8
+
+=item -
 
-=head2 Doc directory symlinks
+Commands will fail rather than warning when they are passed unknown options.
 
-Sometimes it is useful to make a package not contain a /usr/share/doc/package
-directory at all, instead placing just a dangling symlink in the binary
-package, that points to some other doc directory. Policy says this is ok if
-your package depends on the package whose doc directory it uses. To
-accomplish this, just don't tell debhelper to install any documentation
-files into the package, and use dh_link to set up the symlink (or do it by
-hand), and debhelper should do the right thing: notice it is a dangling
-symlink and not try to install a copyright file or changelog.
+=back
+
+=back
 
 =head2 udebs
 
 Debhelper includes support for udebs. To create a udeb with debhelper,
-add "XC-Package-Type: udeb" to the package's stanza in debian/control, and
+add "Package-Type: udeb" to the package's stanza in debian/control, and
 build-depend on debhelper (>= 4.2). Debhelper will try to create udebs that
 comply with debian-installer policy, by making the generated package files
 end in ".udeb", not installing any documentation into a udeb, skipping over