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 Building a package that doesn't have a doc directory:
  60 ----------------------------------------------------
  61
  62 Policy says that if a package depends on some other package, and they build
  63 from the same source, the package can make its doc directory be a symlink to
  64 the doc directory of the package it depends on. If you want to do this with
  65 debhelper, do the following (assumes the package is foo-doc, which depends
  66 on foo):
  67
  68 dh_link usr/share/doc/foo usr/share/doc/foo-doc \
  69         usr/share/doc/foo usr/doc/foo-doc
  70 ...
  71 dh_installdocs -N foo-doc
  72 dh_installexamples -N foo-doc
  73 dh_installchangelogs -N foo-doc
  74
  75 So the dh_link actually sets up the symlinks. Then the three debhelper commands
  76 that normally write into doc directory are told not to act on package
  77 foo-doc. Voila!
  78
  79 Other notes:
  80 -----------
  81
  82 * Note that if you are generating a debian package that has arch-indep and
  83   arch-dependent portions, and you are using dh_movefiles to move the
  84   arch-indep files out of debian/tmp, you need to make sure that dh_movefiles
  85   does this even if only the arch-dependent package is being built (for ports
  86   to other architectures). I handle this in debian/rules.multi by calling
  87   dh_movefiles in the install target.
  88
  89 * Once your package uses debhelper to build, be sure to add
  90   debhelper to your Build-Depends line in debian/control.
  91
  92 * Debhelper's home page is at http://kitenet.net/programs/debhelper/
  93
  94 -- Joey Hess <joeyh@debian.org>