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
  11 Converting from debstd to debhelper:
  12 -----------------------------------
  13
  14 Debhelper is designed to be mostly backwards compatible to debstd. I say
  15 mostly because I haven't made debhelper handle everything that debstd does
  16 yet, and in a few cases, it does things differently (and I hope, better).
  17
  18 In general, you can switch over to using debhelper as follows. In your
  19 debian/rules, where you used to have some lines that read something like:
  20
  21         debstd CHANGES TODO README
  22         dpkg-gencontrol
  23         dpkg --build debian/tmp ..
  24
  25 Remove that and replace it with something like:
  26
  27         dh_installdocs TODO README
  28         dh_installexamples
  29         dh_installmenu
  30         dh_installcron
  31         dh_installmanpages
  32         dh_installchangelogs CHANGES
  33         dh_movefiles
  34         dh_strip
  35         dh_compress
  36         dh_fixperms
  37         dh_suidregister
  38         dh_installdeb
  39         dh_shlibdeps
  40         dh_gencontrol
  41         dh_makeshlibs
  42         dh_md5sums
  43         dh_builddeb
  44
  45 Notice that the parameters sent to debstd get split up among the dh_*
  46 programs. The upstream changelog is passed to dh_installchangelogs, and the
  47 docs are passed to dh_installdocs.
  48
  49 Debstd has many switches, that turn off different parts of it. So if you
  50 were using debstd -m to tell it not to automatically install manpages,
  51 for example, you can just comment out the dh_installmanpages line.
  52
  53 Finally, debstd automatically modified postinst, postrm, etc scripts. Some
  54 of the dehelper apps do that too, but they do it differently. Debstd just
  55 appends its commands to the end of the script. Debhelper requires that you
  56 insert a tag into your scripts, that will tell debhelper where to insert
  57 commands. So if you have postinst, postrm, etc scripts, add a line reading
  58 "#DEBHELPER#" to the end of them.
  59
  60 Once you think it's all set up properly, do a test build of your package. If
  61 it works ok, I recommend that you compare the new package and the old
  62 debstd-generated package very closely. Pay special attention to the postint,
  63 postrm, etc scripts.
  64
  65
  66 Automatic generation of debian install scripts:
  67 ----------------------------------------------
  68
  69 Some debhelper commands will automatically generate parts of debian install
  70 scripts. If you want these automatically generated things included in your
  71 debian install scripts, then you need to add "#DEBHELPER#" to your scripts,
  72 in the place the code should be added. "#DEBHELPER#" will be replaced by any
  73 autogenerated code when you run dh_installdeb.
  74
  75 All scripts that automatically generate code in this way let it be disabled
  76 by the -n parameter.
  77
  78 Note that it will be shell code, so you cannot directly use it in a perl
  79 script. If you would like to embed it into a perl script, here is one way to
  80 do that:
  81
  82 print << `EOF`
  83 #DEBHELPER#
  84 EOF
  85
  86
  87 Notes on multiple binary packages:
  88 ---------------------------------
  89
  90 If your source package generates more than one binary package, debhelper
  91 programs will default to acting on all binary packages when run. If your
  92 source package happens to generate one architecture dependent package, and
  93 another architecture independent package, this is not the correct behavior,
  94 because you need to generate the architecture dependent packages in the
  95 binary-arch debian/rules target, and the architecture independent packages
  96 in the binary-indep debian/rules target.
  97
  98 To facilitate this, as well as give you more control over which packages
  99 are acted on by debhelper programs, all debhelper programs accept the
 100 following parameters:
 101
 102 -a              Act on architecture dependent packages
 103 -i              Act on architecture independent packages
 104 -ppackage       Act on the package named "package" (may be repeated multiple
 105                 times)
 106
 107 These parameters are cumulative. If none are given, the tools default to
 108 affecting all packages.
 109
 110 See examples/rules.multi for an example of how to use this.
 111
 112
 113 Package build directories -- debian/tmp, etc:
 114 --------------------------------------------
 115
 116 By default, all debhelper programs assume that the temporary directory used
 117 for assembling the tree of files in a package is debian/tmp for the first
 118 package listed in debian/control, and debian/<packagename> for each
 119 additional package.
 120
 121 Sometimes, you might want to use some other temporary directory. This is
 122 supported by the -P flag. The directory to use is specified after -P, for
 123 example, "dh_installdocs -Pdebian/tmp", will use debian/tmp as the temporary
 124 directory. Note that if you use -P, the debhelper programs can only be
 125 acting on a single package at a time. So if you have a package that builds
 126 many binary packages, you will need to use the -p flag to specify which
 127 binary package the debhelper program will act on. For example:
 128
 129         dh_installdocs -pfoolib1 -Pdebian/tmp-foolib1
 130         dh_installdocs -pfoolib1-dev -Pdebian/tmp-foolib1-dev
 131         dh_installdocs -pfoolib-bin -Pdebian/tmp-foolib-bin
 132
 133 This uses debian/tmp-<package> as the package build directory.
 134
 135
 136 -- Joey Hess <joeyh@master.debian.org>