doc/README

   1 Debhelper is a collection of programs that can be used in debian/rules files
   2 to automate common tasks related to building debian binary packages. For
   3 further documentation, see the man pages for dh_* commands. For an overview
   4 of debhelper, including a list of all the available commands, see the
   5 debhelper(1) man page.
   6
   7 To help you get started, I've included examples of debian/rules files
   8 that use debhelper commands extensively. See
   9 /usr/share/doc/debhelper/examples/ . These files are also useful as they give
  10 one good order you can run the various debhelper scripts in (though other
  11 variations are possible).
  12
  13 For a more gentle introduction, the maint-guide debian package contains a
  14 tutorial about making your first package using Debhelper.
  15
  16 Debhelper v2:
  17 ------------
  18
  19 Debhelper v2 is a major new version of Debhelper, still under development.
  20 Debhelper will continue to work in v1 compatability mode for now, if you're
  21 interested in trying the new versiln, read the file named "v2".
  22
  23
  24 Starting a new package:
  25 ----------------------
  26
  27 You can just use the example rules files and do the rest of the new package
  28 set up by hand, or you could try the dh-make package, which contains a
  29 "dh_make" command that is similar to debmake, and tries to automate the
  30 process.
  31
  32 Converting from debstd to debhelper:
  33 -----------------------------------
  34
  35 See the file "from-debstd" for documentation on how to do this.
  36
  37 Automatic generation of debian install scripts:
  38 ----------------------------------------------
  39
  40 Some debhelper commands will automatically generate parts of debian install
  41 scripts. If you want these automatically generated things included in your
  42 debian install scripts, then you need to add "#DEBHELPER#" to your scripts,
  43 in the place the code should be added. "#DEBHELPER#" will be replaced by any
  44 auto-generated code when you run dh_installdeb.
  45
  46 All scripts that automatically generate code in this way let it be disabled
  47 by the -n parameter.
  48
  49 Note that it will be shell code, so you cannot directly use it in a perl
  50 script. If you would like to embed it into a perl script, here is one way to
  51 do that (note that I made sure that $1, $2, etc are set with the set command):
  52
  53 my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
  54 #DEBHELPER#
  55 EOF
  56 system ($temp) / 256 == 0
  57         or die "Problem with debhelper scripts: $!\n";
  58
  59 Other notes:
  60 -----------
  61
  62 * Note that if you are generating a debian package that has arch-indep and
  63   arch-dependent portions, and you are using dh_movefiles to move the
  64   arch-indep files out of debian/tmp, you need to make sure that dh_movefiles
  65   does this even if only the arch-dependent package is being built (for ports
  66   to other architectures). I handle this in debian/rules.multi by calling
  67   dh_movefiles in the install target.
  68
  69 * Once your package uses debhelper to build, be sure to add
  70   debhelper to your Build-Depends line in debian/control.
  71
  72 * Debhelper's home page is at http://kitenet.net/programs/debhelper/
  73
  74 -- Joey Hess <joeyh@debian.org>