doc/README

   1 Debhelper is a collection of programs that can be used in debian/rules files
   2 to automate common tasks. For further documentation, see the man pages for
   3 dh_* commands.
   4
   5 To help you get started, I've included examples of debian/rules files
   6 that use debhelper commands extensively. See /usr/doc/debhelper/examples/ .
   7 These files are also useful as they give one good order you can run the
   8 various debhelper scripts in (though other variations are possible).
   9
  10 Starting a new package:
  11 ----------------------
  12
  13 You can just use the example rules files and do the rest of the new package
  14 set up by hand, or you could try the new dh-make package, which contains a
  15 "dh_make" command that is similar to debmake, and tries to automate the
  16 process.
  17
  18 Converting from debstd to debhelper:
  19 -----------------------------------
  20
  21 See the file "from-debstd" for documentation on how to do this.
  22
  23 Automatic generation of debian install scripts:
  24 ----------------------------------------------
  25
  26 Some debhelper commands will automatically generate parts of debian install
  27 scripts. If you want these automatically generated things included in your
  28 debian install scripts, then you need to add "#DEBHELPER#" to your scripts,
  29 in the place the code should be added. "#DEBHELPER#" will be replaced by any
  30 auto-generated code when you run dh_installdeb.
  31
  32 All scripts that automatically generate code in this way let it be disabled
  33 by the -n parameter.
  34
  35 Note that it will be shell code, so you cannot directly use it in a perl
  36 script. If you would like to embed it into a perl script, here is one way to
  37 do that:
  38
  39 print << `EOF`
  40 #DEBHELPER#
  41 EOF
  42
  43
  44 Notes on multiple binary packages:
  45 ---------------------------------
  46
  47 If your source package generates more than one binary package, debhelper
  48 programs will default to acting on all binary packages when run. If your
  49 source package happens to generate one architecture dependent package, and
  50 another architecture independent package, this is not the correct behavior,
  51 because you need to generate the architecture dependent packages in the
  52 binary-arch debian/rules target, and the architecture independent packages
  53 in the binary-indep debian/rules target.
  54
  55 To facilitate this, as well as give you more control over which packages
  56 are acted on by debhelper programs, all debhelper programs accept the
  57 following parameters:
  58
  59 -a              Act on architecture dependent packages
  60 -i              Act on architecture independent packages
  61 -ppackage       Act on the package named "package" (may be repeated multiple
  62                 times)
  63
  64 These parameters are cumulative. If none are given, the tools default to
  65 affecting all packages.
  66
  67 See examples/rules.multi for an example of how to use this.
  68
  69 Package build directories -- debian/tmp, etc:
  70 --------------------------------------------
  71
  72 By default, all debhelper programs assume that the temporary directory used
  73 for assembling the tree of files in a package is debian/tmp for the first
  74 package listed in debian/control, and debian/<packagename> for each
  75 additional package.
  76
  77 Sometimes, you might want to use some other temporary directory. This is
  78 supported by the -P flag. The directory to use is specified after -P, for
  79 example, "dh_installdocs -Pdebian/tmp", will use debian/tmp as the temporary
  80 directory. Note that if you use -P, the debhelper programs can only be
  81 acting on a single package at a time. So if you have a package that builds
  82 many binary packages, you will need to use the -p flag to specify which
  83 binary package the debhelper program will act on. For example:
  84
  85         dh_installdocs -pfoolib1 -Pdebian/tmp-foolib1
  86         dh_installdocs -pfoolib1-dev -Pdebian/tmp-foolib1-dev
  87         dh_installdocs -pfoolib-bin -Pdebian/tmp-foolib-bin
  88
  89 This uses debian/tmp-<package> as the package build directory.
  90
  91 Other notes:
  92 -----------
  93
  94 * In general, if any debhelper program needs a directory to exist under
  95   debian/, it will create it. I haven't bothered to document this in all the
  96   man pages, but for example, dh_installdeb knows to make debian/tmp/DEBIAN/
  97   before trying to put files there, dh_installmenu knows you need a
  98   debian/tmp/usr/lib/menu/ before installing the menu files, etc.
  99
 100 -- Joey Hess <joeyh@master.debian.org>