Debhelper is a collection of programs that can be used in debian/rules files
to automate common tasks related to building debian binary packages. For 
further documentation, see the man pages for dh_* commands. For an overview 
of debhelper, including a list of all the available commands, see the
debhelper(1) man page.

To help you get started, I've included examples of debian/rules files
that use debhelper commands extensively. See 
/usr/share/doc/debhelper/examples/ . These files are also useful as they give
one good order you can run the various debhelper scripts in (though other
variations are possible).

For a more gentle introduction, the maint-guide debian package contains a
tutorial about making your first package using Debhelper.

Debhelper v2:
------------

Debhelper v2 is a major new version of Debhelper, still under development.
Debhelper will continue to work in v1 compatability mode for now, if you're
interested in trying the new versiln, read the file named "v2".


Starting a new package:
----------------------

You can just use the example rules files and do the rest of the new package
set up by hand, or you could try the dh-make package, which contains a
"dh_make" command that is similar to debmake, and tries to automate the
process.

Converting from debstd to debhelper:
-----------------------------------

See the file "from-debstd" for documentation on how to do this.

Automatic generation of debian install scripts:
----------------------------------------------

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.

All scripts that automatically generate code in this way let it be disabled
by the -n parameter.

Note that it 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: $!\n";

Other notes:
-----------

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 debian/rules.multi by calling
dh_movefiles in the install target.

Debhelper's home page is at http://kitenet.net/programs/debhelper/

-- Joey Hess <joeyh@master.debian.org>