=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
=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
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
=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>
=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>
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
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
=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<--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
+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
it modifies its behavior in various ways.
Tell debhelper what compatibility level to use by writing a number to
-debian/compat. For example, to turn on V7 mode:
+debian/compat. For example, to turn on v7 mode:
% echo 7 > debian/compat
=over 4
-=item V1
+=item v1
This is the original debhelper compatibility level, and so it is the default
one. In this mode, debhelper will use debian/tmp as the package tree
This mode is deprecated.
-=item V2
+=item v2
In this mode, debhelper will consistently use debian/<package>
as the package tree directory for every package that is built.
This mode is deprecated.
-=item V3
+=item v3
-This mode works like V2, with the following additions:
+This mode works like v2, with the following additions:
=over 8
This mode is deprecated.
-=item V4
+=item v4
-Changes from V3 are:
+Changes from v3 are:
=over 8
=back
-=item V5
+This mode is deprecated.
-Changes from V4 are:
+=item v5
+
+Changes from v4 are:
=over 8
=back
-=item V6
+=item v6
-Changes from V5 are:
+Changes from v5 are:
=over 8
=back
-=item V7
+=item v7
This is the recommended mode of operation.
-Changes from V6 are:
+Changes from v6 are:
=over 8
=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
-=head2 Doc directory symlinks
+=item -
+
+Commands will fail rather than warning when they are passed unknown options.
+
+=item -
+
+dh_makeshlibs will run dpkg-gensymbols on all shared libraries that it
+generates shlibs files for. So -X can be used to exclude libraries.
+Also, libraries in unusual locations that dpkg-gensymbols would not
+have processed before will be passed to it, a behavior change that
+can cause some packages to fail to build.
+
+=item -
-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.
+dh requires the sequence to run be specified as the first parameter, and
+any switches come after it. Ie, use "dh $@ --foo", not "dh --foo $@"
+
+=item
+
+dh_auto_* prefer to use perl's Module::Build in preference to Makefile.PL.
+
+=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