X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=debhelper.1;h=3c3a3ccdc767c749dc90349969408ac94a2b82d3;hb=44afd80cb40da906535992cd99d8d24a2a60414e;hp=f32966662a0a990bf5aae54e374b1c50f5f9a853;hpb=a4caa9e05bc2b7e4ea034026cf0b2cda3461d4b2;p=debhelper.git diff --git a/debhelper.1 b/debhelper.1 index f329666..3c3a3cc 100644 --- a/debhelper.1 +++ b/debhelper.1 @@ -3,15 +3,60 @@ debhelper \- overview of the debhelper commands .SH SYNOPSIS .B dh_* -.I "[-v] [-a] [-i] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]" +.I "[-v] [-a] [-i] [-s] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]" .SH "DESCRIPTION" -Debhelper is a collection of programs that can be used in debian/rules files -to automate common tasks related to building debian binary packages. All the -debhelper commands accept a set of options, and this man page is here to -document those options and to document debhelper as a whole. For additional -options, and documentation for each individual command, see the commands' own -man pages. -.SH "SHARED DEBHLPER OPTIONS" +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. +.P +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 +/usr/share/doc/debhelper/examples/ . +.P +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 +.BR 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. +.SH "DEBHELPER COMMANDS" +Here is the complete list of available debhelper commands. See their man +pages for additional documentation. +#LIST# +.SH "DEBHELPER CONFIG FILES" +Many debhelper commands make use of files in debian/ to control what they +do. Besides the common debian/changelog and 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/.foo (where of course, +is replaced with the package that is being acted on). +.P +For example, +dh_installdocs uses files named debian/.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. +.P +Note that if a package is the first (or only) binary package listed in +debian/control, debhelper will use debian/foo if no debian/.foo +file can be found. +.P +In some rare cases, you may want to have different versions of these files +for different architectures. If files named debian/.foo. +exist, where is the same as the output of "dpkg --print-architecture", +then they will be used in preference to other, more general files. +.P +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 '*') in the files. +.SH "SHARED DEBHELPER OPTIONS" +The following command line options are supported by all debhelper programs. .TP .B \-v, \--verbose Verbose mode: show all commands that modify the package build directory. @@ -29,12 +74,36 @@ Act on all architecture independent packages. .B \-ppackage, \--package=package Act on the package named "package". .TP +.B \-s, \--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. +.TP .B \-Npackage, \--no-package=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. .TP .B \-Ptmpdir, \--tmpdir=tmpdir -Use "tmpdir" for package build directory. +Use "tmpdir" for package build directory. The default is debian/ +.SH "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 the +option does. +.TP +.B \-n +Do not modify postinst/postrm/etc scripts. +.TP +.B \-Xitem, \--exclude=item +Exclude an item from processing. This option may be used multiple times, +to exclude more than one thing. +.TP +.B \-A, \-all +Makes files or other items that are specified on the command line take effect +in ALL packages acted on, not just the first. .SH NOTES .TP .B Multiple binary package support @@ -48,27 +117,49 @@ 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 +are acted on by debhelper programs, all debhelper programs accept the .B -a , .B -i -, and +, .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. .P See -.BR /usr/doc/debhelper/examples/rules.multi +.BR /usr/share/doc/debhelper/examples/rules.multi for an example of how to use this. .RE .TP +.B Automatic generation of debian install scripts +.RS +Some debhelper commands will automatically generate parts of debian install +scripts. If you want these automatically generated things included in your +debian install 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. +.P +All scripts that automatically generate code in this way let it be disabled +by the -n parameter (see above). +.P +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: $!"; +.RE +.TP .B Package build directories .RS By default, all debhelper programs assume that the temporary directory used -for assembling the tree of files in a package is debian/tmp for the first -package listed in debian/control, and debian/ for each -additional package. +for assembling the tree of files in a package is debian/. .P Sometimes, you might want to use some other temporary directory. This is supported by the @@ -80,25 +171,99 @@ many binary packages, you will need to use the -p flag to specify which binary package the debhelper program will act on. .RE .TP +.B Debhelper compatability levels +.RS +From time to time, major non-backwards-compatabile 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 DH_COMPAT environment variable was introduced. +DH_COMPAT may be set to a number, to determine which major revision of +debhelper should be used. There are currently 3: +.TP +.B V1 +Setting DH_COMPAT=1 (or leaving it unset) causes debhelper to act in +compatability mode. It 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. +.TP +.B V2 +Setting DH_COMPAT=2 causes debhelper to consitently use debian/ +as the package tree directory for every package that is built. This +mode is currently set by default in all the example rules files, and you +are encouraged to use it. +.TP +.B V3 +Setting DH_COMPAT=3 does everything V2 does, plus: +.RS +.TP +.B * +Debhelper config files support globbing via * and ?, when appropriate. To +turn this off and use those characters raw, just prefix with a backspash. +.TP +.B * +dh_makeshlibs makes the postinst and postrm scripts call ldconfig. +.TP +.B * +Every file in etc/ is automatically flagged as a conffile by dh_installdeb. +.RE +.RE +.TP +.B Doc directory symlinks +.RS +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. +.RE +.TP .B Other notes +.RS 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/tmp/DEBIAN/ +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/tmp/usr/lib/menu/ before installing the menu files, etc. +debian//usr/lib/menu/ before installing the menu files, etc. +.P +Note that if you are generating a debian package that has arch-indep and +arch-dependent portions, and you are using dh_movefiles to move the +arch-indep files out of debian/tmp, you need to make sure that dh_movefiles +does this even if only the arch-dependent package is being built (for +ports to other architectures). I handle this in the example rules file +"rules.multi" by calling dh_movefiles in the install target. +.P +Once your package uses debhelper to build, be sure to add +debhelper to your Build-Depends line in debian/control. +.RE .SH ENVIRONMENT .TP .I DH_VERBOSE Enables verbose mode. .TP +.I DH_COMPAT +Specifies what compatability level debhelper should run at. See above. +.TP .I DH_NO_ACT Enables no-act mode. -.SH "SEE ALSO" .TP -.BR /usr/doc/debhelper/README -An introduction to debhelper. +.I DH_OPTIONS +Anything in this variable will be prepended to the command line +arguments of all debhelper commands. This in 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 use "dh_testversion 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. +.SH "SEE ALSO" .TP -.BR /usr/doc/debhelper/examples/ +.BR /usr/share/doc/debhelper/examples/ A set of example debian/rules files that use debhelper. +.TP +.BR http://kitenet.net/programs/debhelper/ +Debhelper web site. .SH AUTHOR -Joey Hess +Joey Hess