r359: * I started work on debhelper v2 over a year ago, with a long list of

     changes I hoped to get in that broke backwards compatability. That
     development stalled after only the most important change was made,
     although I did get out over 100 releases in the debhelper 2.0.x tree.
     In the meantime, lots of packages have switched to using v2, despite my
     warnings that doing so leaves packages open to being broken without
     notice until v2 is complete.
   * Therefore, I am calling v2 complete, as it is. Future non-compatabile
     changes will happen in v3, which will be started soon. This means that
     by using debhelper v2, one major thing changes: debhelper uses
     debian/<package> as the temporary directory for *all* packages;
     debian/tmp is no longer used to build binary packages out of. This is
     very useful for multi-binary packages, and I reccommend everyone
     switch to v2.
   * Updated example rules files to use v2 by default.
   * Updated all documentation to assume that v2 is being used.
   * Added a few notes for people still using v1.
   * Moved all of the README into debhelper(1).

1 files changed, 92 insertions, 24 deletions

diff --git a/debhelper.1 b/debhelper.1
index 6ed7ef7a..acb6a705 100644
--- a/debhelper.1
+++ b/debhelper.1
@@ -5,12 +5,30 @@ debhelper \- overview of the debhelper commands
 .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.
+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 "SHARED DEBHLPER OPTIONS"
 The following command line options are supported by all debhelper programs.
 .TP
@@ -44,10 +62,10 @@ 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/<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
@@ -89,13 +107,32 @@ See
 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
@@ -107,27 +144,61 @@ 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/<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 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.
@@ -142,9 +213,6 @@ 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/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