X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=debhelper.pod;h=a4765baba8367f458a96f5fa1cc80a07056a061a;hb=9e5fdb82a41c79453c6645757df5be4716d4cd90;hp=2cc4f38f03c5d884f18ad69a7d508e5c80bad16b;hpb=472a8f123ef2fde0eb5ad29b8ec95449097fee6f;p=debhelper.git diff --git a/debhelper.pod b/debhelper.pod index 2cc4f38..a4765ba 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 @@ -62,9 +74,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 @@ -92,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> @@ -105,19 +119,22 @@ 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, B<--no-package=>I 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 Ignore the specified file. This can be used if debian/ contains a debhelper @@ -165,6 +182,67 @@ 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<--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) 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 @@ -333,6 +411,8 @@ dh_link will correct existing links to conform with policy. =back +This mode is deprecated. + =item V5 Changes from V4 are: @@ -366,8 +446,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 +464,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 +478,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 - @@ -420,17 +500,6 @@ none is specified. =back -=head2 Doc directory symlinks - -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. - =head2 udebs Debhelper includes support for udebs. To create a udeb with debhelper, @@ -477,10 +546,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