X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=debhelper.pod;h=554b7f7834eb113941411044b2b0cd7b1592cfd5;hb=93a73a7ead5d90accb7259a46efdebab113e6550;hp=8ea3f31fa11d7dfc033461ff5588825c02ebfeda;hpb=dace0773fe5f66fdf040f54383322e21a65fa1e8;p=debhelper.git diff --git a/debhelper.pod b/debhelper.pod index 8ea3f31..554b7f7 100644 --- 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 @@ -144,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 + +This is used by L 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 @@ -205,23 +224,22 @@ 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<-j>[I], B<--parallel>[I<=maximum>] +=item B<--parallel> -Indicate that a source package supports building using multiple parallel -processes. However, the package will be built in this mode only if the build -system supports this feature and tag I is present in the -DEB_BUILD_OPTIONS environment variable (as per Debian Policy section 4.9.1). -The number of spawned parallel processes will be the smallest value of I, -I (if specified) or a build system specific limit. +Enable parallel builds if underlying build system supports them. +The number of parallel jobs is controlled by the +DEB_BUILD_OPTIONS environment variable (L) at +build time. It might also be subject to a build system specific limit. -If value of I is 1, parallel building will be forcefully disabled. -Such construct can be used to negate effects of the previously specified -I<--parallel> option. +If this option is not specified, debhelper currently defaults to not +allowing parallel package builds. -If I<--parallel> is not specified, a debhelper build system will neither -attempt to enforce nor prevent parallel building. This typically means a source -package does not to support parallel building or enforces it in other ways -(e.g. by modifying MAKEFLAGS manually). +=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> @@ -319,7 +337,7 @@ introduced. You tell debhelper which compatibility level it should use, and 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 @@ -334,7 +352,7 @@ These are the available compatibility levels: =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 @@ -343,16 +361,16 @@ debian/ for all other packages listed in the control file. This mode is deprecated. -=item V2 +=item v2 In this mode, debhelper will consistently use debian/ 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 @@ -373,9 +391,9 @@ Every file in etc/ is automatically flagged as a conffile by dh_installdeb. This mode is deprecated. -=item V4 +=item v4 -Changes from V3 are: +Changes from v3 are: =over 8 @@ -402,9 +420,9 @@ dh_link will correct existing links to conform with policy. This mode is deprecated. -=item V5 +=item v5 -Changes from V4 are: +Changes from v4 are: =over 8 @@ -427,9 +445,9 @@ dh_install errors out if wildcards expand to nothing. =back -=item V6 +=item v6 -Changes from V5 are: +Changes from v5 are: =over 8 @@ -457,11 +475,11 @@ directory. In previous compatibility levels it silently refuses to do this. =back -=item V7 +=item v7 This is the recommended mode of operation. -Changes from V6 are: +Changes from v6 are: =over 8 @@ -487,12 +505,44 @@ none is specified. =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 - + +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 - + +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