X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=debhelper.pod;h=554b7f7834eb113941411044b2b0cd7b1592cfd5;hb=93a73a7ead5d90accb7259a46efdebab113e6550;hp=ad40d71419e0c0a428041d23e53f5e7472de5ca1;hpb=56e952b7c137f641983333ce200c445946def257;p=debhelper.git diff --git a/debhelper.pod b/debhelper.pod index ad40d71..554b7f7 100644 --- a/debhelper.pod +++ b/debhelper.pod @@ -17,9 +17,8 @@ policy changes, and packages that use them will require only a rebuild to comply with the new policy. A typical debian/rules file that uses debhelper will call several debhelper -commands in sequence. Debhelper commands are all named with a "dh_" prefix. -Examples of rules files that use debhelper are in -F +commands in sequence, or use L to automate this process. Examples of +rules files that use debhelper are in F To create a new debian package using debhelper, you can just copy one of the sample rules files and edit it by hand. Or you can try the dh-make @@ -29,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 @@ -38,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 @@ -63,8 +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 --print-architecture", +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 @@ -72,6 +85,9 @@ files. Documentation or example files to install, files to move, and so on. When appropriate, in cases like these, you can use standard shell wildcard characters ('?' and '*' and '[..]' character classes) in the files. +You can also put comments in these files; lines beginning with "#" are +ignored. + =head1 SHARED DEBHELPER OPTIONS The following command line options are supported by all debhelper programs. @@ -89,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> @@ -102,19 +119,32 @@ 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 independant. +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 +config file that a debhelper command should not act on. Note that +debian/compat, debian/control, and debian/changelog can't be ignored, but +then, there should never be a reason to ignore those files. + +For example, if upstream ships a debian/init that you don't want +dh_installinit to install, use --ignore=debian/init + =item B<-P>I, B<--tmpdir=>I Use "tmpdir" for package build directory. The default is debian/ @@ -126,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 @@ -145,13 +182,74 @@ Do not modify postinst/postrm/etc scripts. Exclude an item from processing. This option may be used multiple times, to exclude more than one thing. -=item B<-A>, B<-all> +=item B<-A>, B<--all> Makes files or other items that are specified on the command line take effect 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 @@ -170,9 +268,6 @@ B<-a>, B<-i>, B<-p>, and B<-s> parameters. These parameters are cumulative. If none are given, debhelper programs default to acting on all packages listed in the control file. -See F for an example of how to -use this in a package that generates multiple binary packages. - =head2 Automatic generation of debian install scripts Some debhelper commands will automatically generate parts of debian @@ -237,35 +332,45 @@ act on. From time to time, major non-backwards-compatible changes need to be made to debhelper, to keep it clean and well-designed as needs change and its author gains more experience. To prevent such major changes from breaking -existing packages, the concept of debhelper compatability levels was -introduced. You tell debhelper which compatability level it should use, and +existing packages, the concept of debhelper compatibility levels was +introduced. You tell debhelper which compatibility level it should use, and it modifies its behavior in various ways. -You tell debhelper what compatability level to use by writing a number to -debian/compat. For example, to turn on V4 mode: +Tell debhelper what compatibility level to use by writing a number to +debian/compat. For example, to turn on v7 mode: - % echo 4 > debian/compat + % echo 7 > debian/compat -These are the available compatablity levels: +Unless otherwise indicated, all debhelper documentation assumes that you +are using the most recent compatibility level, and in most cases does not +indicate if the behavior is different in an earlier compatibility level, so +if you are not using the most recent compatibility level, you're advised to +read below for notes about what is different in earlier compatibility +levels. + +These are the available compatibility levels: =over 4 -=item V1 +=item v1 -This is the original debhelper compatability level, and so it is the default +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 directory for the first binary package listed in the control file, while using 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. -=item V3 +This mode is deprecated. + +=item v3 -This mode works like V2, with the following additions: +This mode works like v2, with the following additions: =over 8 @@ -284,22 +389,23 @@ Every file in etc/ is automatically flagged as a conffile by dh_installdeb. =back -=item V4 +This mode is deprecated. + +=item v4 -This is the reccommended mode of operation. It does everything V3 does, -plus: +Changes from v3 are: =over 8 =item - dh_makeshlibs -V will not include the debian part of the version number in -the generated dependancy line in the shlibs file. +the generated dependency line in the shlibs file. =item - You are encouraged to put the new ${misc:Depends} into debian/control to -suppliment the ${shlibs:Depends} field. +supplement the ${shlibs:Depends} field. =item - @@ -312,18 +418,135 @@ dh_link will correct existing links to conform with policy. =back +This mode is deprecated. + +=item v5 + +Changes from v4 are: + +=over 8 + +=item - + +Comments are ignored in debhelper config files. + +=item - + +dh_strip --dbg-package now specifies the name of a package to put debugging +symbols in, not the packages to take the symbols from. + +=item - + +dh_installdocs skips installing empty files. + +=item - + +dh_install errors out if wildcards expand to nothing. + +=back + +=item v6 + +Changes from v5 are: + +=over 8 + +=item - + +Commands that generate maintainer script fragments will order the +fragments in reverse order for the prerm and postrm scripts. + +=item - + +dh_installwm will install a slave manpage link for x-window-manager.1.gz, +if it sees the man page in usr/share/man/man1 in the package build +directory. + +=item - + +dh_builddeb did not previously delete everything matching +DH_ALWAYS_EXCLUDE, if it was set to a list of things to exclude, such as +"CVS:.svn:.git". Now it does. + +=item - + +dh_installman allows overwriting existing man pages in the package build +directory. In previous compatibility levels it silently refuses to do this. + +=back + +=item v7 + +This is the recommended mode of operation. + +Changes from v6 are: + +=over 8 + +=item - + +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 - + +dh_clean will read debian/clean and delete files listed there. + +=item - + +dh_clean will delete toplevel *-stamp files. + +=item - + +dh_installchangelogs will guess at what file is the upstream changelog if +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 Doc directory symlinks +=head2 udebs -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. +Debhelper includes support for udebs. To create a udeb with debhelper, +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 +preinst, postrm, prerm, and config scripts, etc. =head2 Other notes @@ -331,15 +554,15 @@ In general, if any debhelper program needs a directory to exist under debian/, it will create it. I haven't bothered to document this in all the man pages, but for example, dh_installdeb knows to make debian//DEBIAN/ before trying to put files there, dh_installmenu knows you need a -debian//usr/lib/menu/ before installing the menu files, etc. +debian//usr/share/menu/ before installing the menu files, etc. Once your package uses debhelper to build, be sure to add debhelper to your Build-Depends line in debian/control. You should -build-depend on a verson of debhelper equal to (or greater than) the -debhelper compatability level your package uses. So if your package used -compatability level 4: +build-depend on a version of debhelper equal to (or greater than) the +debhelper compatibility level your package uses. So if your package used +compatibility level 7: - Build-Depends: debhelper (>= 4) + Build-Depends: debhelper (>= 7) =head1 ENVIRONMENT @@ -361,13 +584,14 @@ 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. If you use DH_OPTIONS, be sure to build depend on "debhelper >= 1.1.17" -- -older debhelpers will ignore it and do things you don't want them to. One very -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. +Anything in this variable will be prepended to the command line arguments +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 @@ -395,7 +619,7 @@ DH_ALWAYS_EXCLUDE=CVS:.svn A set of example debian/rules files that use debhelper. -=item L +=item L Debhelper web site.