.B dh_*
.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 philospohy 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/<package>.foo (where <package> of course,
+is replaced with the package that is being acted on).
+.P
+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.
+.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/<package>.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/<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.
+.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
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.
-Constrast to the -a flag, which makes the command work on all packages that
+Contrast to the -a flag, which makes the command work on all packages that
are not architecture independant.
.TP
.B \-Npackage, \--no-package=package
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/<package>
.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 explination of what the
+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.
+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 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
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/<packagename> for each
-additional package. If DH_COMPAT=2, debian/<packagename> is always used,
-even for the first package.
+for assembling the tree of files in a package is debian/<packagename>.
.P
Sometimes, you might want to use some other temporary directory. This is
supported by the
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/<package> 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/<package>
+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 will make debhelper start using new v3 features as
+they are implemented. This will cause its behavior to change without
+notice, and so may break packages that use it. See the file
+"/usr/share/doc/debhelper/v3" for more information about planned
+changes.
+.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/<foo>/DEBIAN/
before trying to put files there, dh_installmenu knows you need a
debian/<foo>/usr/lib/menu/ before installing the menu files, etc.
-.SH "DEBHELPER COMMANDS"
-Here is the complete list of available debhelper commands.
-#LIST#
+.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. The default is 1,
-which makes debhelper behave in a manner compatable with the 1.x series of
-debhelper. If set to 2, debhelper's behavior will change to use the new
-features of the 2.x series. Use this with caution, as the 2.x series makes
-major changes that will break most packages. For documentation on these
-changes, read /usr/share/doc/debhelper/v2
+Specifies what compatability level debhelper should run at. See above.
.TP
.I DH_NO_ACT
Enables no-act mode.
your debian/rules file. See the make documentation for details on doing this.
.SH "SEE ALSO"
.TP
-.BR /usr/share/doc/debhelper/README
-An introduction to debhelper.
-.TP
.BR /usr/share/doc/debhelper/examples/
A set of example debian/rules files that use debhelper.
.TP
projects / debhelper.git / blobdiff