diff options
Diffstat (limited to 'debhelper.pod')
-rw-r--r-- | debhelper.pod | 404 |
1 files changed, 404 insertions, 0 deletions
diff --git a/debhelper.pod b/debhelper.pod new file mode 100644 index 00000000..3fa2e2d1 --- /dev/null +++ b/debhelper.pod @@ -0,0 +1,404 @@ +=head1 NAME + +debhelper - the debhelper tool suite + +=head1 SYNOPSIS + +B<dh_>I<*> [B<-v>] [B<-a>] [B<-i>] [B<-s>] [B<--no-act>] [B<-ppackage>] [B<-Npackage] [-Ptmpdir>] + +=head1 DESCRIPTION + +Debhelper is used to help you build a debian package. The philosophy behind +debhelper is to provide a collection of small, simple, and easily +understood tools that are used in debian/rules to automate various common +aspects of building a package. This means less work for you, the packager. +It also, to some degree means that these tools can be changed if debian +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</usr/share/doc/debhelper/examples/> + +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 +package, which contains a L<dh_make|dh_make(1)> command that partially +automates the process. For a more gentle introduction, the maint-guide debian +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 +pages for additional documentation. + +=over 4 + +#LIST# + +=back + +=head1 DEBHELPER CONFIG FILES + +Many debhelper commands make use of files in F<debian/> to control what they +do. Besides the common F<debian/changelog> and F<debian/control>, which are +in all packages, not just those using debhelper, some additional files can +be used to configure the behavior of specific debhelper commands. These +files are typically named debian/package.foo (where "package" of course, +is replaced with the package that is being acted on). + +For example, dh_installdocs uses files named debian/package.docs to list +the documentation files it will install. See the man pages of individual +commands for details about the names and formats of the files they use. +Generally, these files will list files to act on, one file per line. Some +programs in debhelper use pairs of files and destinations or slightly more +complicated formats. + +Note that if a package is the first (or only) binary package listed in +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", +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 +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. + +=head1 SHARED DEBHELPER OPTIONS + +The following command line options are supported by all debhelper programs. + +=over 4 + +=item B<-v>, B<--verbose> + +Verbose mode: show all commands that modify the package build directory. + +=item B<--no-act> + +Do not really do anything. If used with -v, the result is that the command +will output what it would have done. + +=item B<-a>, B<--arch> + +Act on all architecture dependent packages. + +=item B<-i>, B<--indep> + +Act on all architecture independent packages. + +=item B<->I<ppackage>, B<--package=>I<package> + +Act on the package named "package". This option may be specified multiple +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. + +=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<-P>I<tmpdir>, B<--tmpdir=>I<tmpdir> + +Use "tmpdir" for package build directory. The default is debian/<package> + +=item B<--mainpackage=>I<package> + +This little-used option changes the package which debhelper considers the +"main package", that is, the first one listed in debian/control, and the +one for which debian/foo files can be used instead of the usual +debian/package.foo files. + +=back + +=head1 COMMON DEBHELPER OPTIONS + +The following command line options are supported by some debhelper programs. +See the man page of each program for a complete explanation of what each +option does. + +=over 4 + +=item B<-n> + +Do not modify postinst/postrm/etc scripts. + +=item B<-X>I<item>, B<--exclude=>I<item> + +Exclude an item from processing. This option may be used multiple times, +to exclude more than one thing. + +=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 NOTES + +=head2 Multiple binary package support + +If your source package generates more than one binary package, debhelper +programs will default to acting on all binary packages when run. If your +source package happens to generate one architecture dependent package, and +another architecture independent package, this is not the correct behavior, +because you need to generate the architecture dependent packages in the +binary-arch debian/rules target, and the architecture independent packages +in the binary-indep debian/rules target. + +To facilitate this, as well as give you more control over which packages +are acted on by debhelper programs, all debhelper programs accept the +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</usr/share/doc/debhelper/examples/rules.multi> 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 +maintainer scripts. If you want these automatically generated things +included in your existing debian maintainer scripts, then you need to add +"#DEBHELPER#" to your scripts, in the place the code should be added. +"#DEBHELPER#" will be replaced by any auto-generated code when you run +dh_installdeb. + +If a script does not exist at all and debhelper needs to add something to +it, then debhelper will create the complete script. + +All debhelper commands that automatically generate code in this way let it +be disabled by the -n parameter (see above). + +Note that the inserted code will be shell code, so you cannot directly use +it in a perl script. If you would like to embed it into a perl script, here +is one way to do that (note that I made sure that $1, $2, etc are set with +the set command): + + my $temp="set -e\nset -- @ARGV\n" . << 'EOF'; + #DEBHELPER# + EOF + system ($temp) / 256 == 0 + or die "Problem with debhelper scripts: $!"; + +=head2 Automatic generation of miscellaneous dependencies. + +Some debhelper commands may make the generated package need to depend on +some other packages. For example, if you use L<dh_installdebconf(1)>, your +package will generally need to depend on debconf. Or if you use +L<dh_installxfonts(1)>, your package will generally need to depend on a +particular version of xutils. Keeping track of these miscellaneous +dependencies can be annoying since they are dependant on how debhelper does +things, so debhelper offers a way to automate it. + +All commands of this type, besides documenting what dependencies may be +needed on their man pages, will automatically generate a substvar called +${misc:Depends}. If you put that token into your debian/control file, it +will be expanded to the dependencies debhelper figures you need. + +This is entirely independent of the standard ${shlibs:Depends} generated by +L<dh_makeshlibs(1)>, and the ${perl:Depends} generated by L<dh_perl(1)>. +You can choose not to use any of these, if debhelper's guesses don't match +reality. + +=head2 Package build directories + +By default, all debhelper programs assume that the temporary directory used +for assembling the tree of files in a package is debian/<package>. + +Sometimes, you might want to use some other temporary directory. This is +supported by the -P flag. For example, "dh_installdocs -Pdebian/tmp", will +use debian/tmp as the temporary directory. Note that if you use -P, the +debhelper programs can only be acting on a single package at a time. So if +you have a package that builds many binary packages, you will need to also +use the -p flag to specify which binary package the debhelper program will +act on. + +=head2 Debhelper compatibility levels + +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 +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: + + % echo 4 > debian/compat + +These are the available compatablity levels: + +=over 4 + +=item V1 + +This is the original debhelper compatability 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/<package> for all other packages listed in the control file. +This mode is deprecated. + +=item V2 + +In this mode, debhelper will consistently use debian/<package> +as the package tree directory for every package that is built. + +=item V3 + +This mode works like V2, with the following additions: + +=over 8 + +=item - + +Debhelper config files support globbing via * and ?, when appropriate. To +turn this off and use those characters raw, just prefix with a backslash. + +=item - + +dh_makeshlibs makes the postinst and postrm scripts call ldconfig. + +=item - + +Every file in etc/ is automatically flagged as a conffile by dh_installdeb. + +=back + +=item V4 + +This is the reccommended mode of operation. It does everything V3 does, +plus: + +=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. + +=item - + +You are encouraged to put the new ${misc:Depends} into debian/control to +suppliment the ${shlibs:Depends} field. + +=item - + +dh_fixperms will make all files in bin/ directories and in etc/init.d +executable. + +=item - + +dh_link will correct existing links to conform with policy. + +=back + +=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 Other notes + +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/<package>/DEBIAN/ +before trying to put files there, dh_installmenu knows you need a +debian/<package>/usr/lib/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-Depends: debhelper (>= 4) + +=head1 ENVIRONMENT + +=over 4 + +=item DH_VERBOSE + +Set to 1 to enable verbose mode. Debhelper will output every command it runs +that modifies files on the build system. + +=item DH_COMPAT + +Temporarily specifies what compatibility level debhelper should run at, +overriding any value in debian/compat. + +=item DH_NO_ACT + +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. + +=item DH_ALWAYS_EXCLUDE + +If set, this adds the value the variable is set to to the -X options of all +commands that support the -X option. Moreover, dh_builddeb will rm -rf +anything that matches the value in your package build tree. + +This can be useful if you are doing a build from a CVS source tree, in +which case setting DH_ALWAYS_EXCLUDE=CVS will prevent any CVS directories +from sneaking into the package you build. Or, if a package has a source +tarball that (unwisely) includes CVS directories, you might want to export +DH_ALWAYS_EXCLUDE=CVS in debian/rules, to make it take effect wherever +your package is built. + +Multiple things to exclude can be separated with colons, as in +DH_ALWAYS_EXCLUDE=CVS:.svn + +=back + +=head1 SEE ALSO + +=over 4 + +=item F</usr/share/doc/debhelper/examples/> + +A set of example debian/rules files that use debhelper. + +=item L<http://kitenet.net/programs/debhelper/> + +Debhelper web site. + +=back + +=head1 AUTHOR + +Joey Hess <joeyh@debian.org> + +=cut |