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 an example of a debian/rules file
   6 that uses debhelper commands extensivly. See
   7 /usr/doc/debhelper/examples/rules . These files are also useful as they give
   8 one good order you can run the different debhelper scripts in (though other
   9 variations are possible).
  10
  11
  12 Converting from debstd to debhelper:
  13 -----------------------------------
  14
  15 Debhelper is designed to be mostly backwards compatable to debstd. I say
  16 mostly becuase I haven't made debhelper handle everything that debstd does
  17 yet, and in a few cases, it does things differently (and I hope, better).
  18
  19 In general, you can switch over to using debhelper as follows. In your
  20 debian/rules, where you used to have some lines that read something like:
  21
  22         debstd CHANGES TODO README
  23         dpkg-gencontrol
  24         dpkg --build debian/tmp ..
  25
  26 Remove that and replace it with something like:
  27
  28         dh_installdocs TODO README
  29         dh_installexamples
  30         dh_installmenu
  31         dh_installcron
  32         dh_installmanpages
  33         dh_installchangelogs CHANGES
  34         dh_strip
  35         dh_compress
  36         dh_fixperms
  37         dh_suidregister
  38         dh_installdebfiles
  39         dh_makeshlibs
  40         dh_md5sums
  41         dh_builddeb
  42
  43 Notice that the parameters sent to debstd get split up among the dh_*
  44 programs. The upstream changelog is passed to dh_installchangelogs, and the
  45 docs are passed to dh_installdocs.
  46
  47 Debstd has many switches, that turn off differnt parts of it. So if you
  48 were using debstd -m to tell it not to automatically install manpages,
  49 for example, you can just comment out the dh_installmanpages line.
  50
  51 Finally, debstd automatically modified postinst, postrm, etc scripts. Some
  52 of the dehelper apps do that too, but they do it differnently. Debstd just
  53 appends its commands to the end of the script. Debhelper reqyires that you
  54 insert a tag into your scripts, that will tell debhelper where to insert
  55 commands. So if you have postinst, postrm, etc scripts, add a line reading
  56 "#DEBHELPER" to the end of them.
  57
  58 Once you think it's all set up properly, do a test build of your package. If
  59 it works ok, I reccommend that you compare the new package and the old
  60 debstd-generated package very closely. Pay special attention to the postint,
  61 postrm, etc scripts.
  62
  63
  64 Automatic generation of debian install scripts:
  65 ----------------------------------------------
  66
  67 Some debhelper commands will automatically generate parts of debian install
  68 scripts. If you want these automatically generated things included in your
  69 debian install scripts, then you need to add "#DEBHELPER#" to your scripts,
  70 in the place the code should be added. "#DEBHELPER#" will be replaced by any
  71 autogenerated code when you run dh_installdebfiles.
  72
  73 All scripts that automatically generate code in this way let it be disabled
  74 by the -n parameter.
  75
  76 Note that it will be shell code, so you cannot directly use it in a perl
  77 script.
  78
  79
  80 Notes on multiple binary packages:
  81 ---------------------------------
  82
  83 If your source package generates more than one binary package, debhelper
  84 programs will default to acting on all binary packages when run. If your
  85 source package happens to generate one architecture dependent package, and
  86 another architecture independent package, this is not the correct behavior,
  87 because you need to generate the architecture dependent packages in the
  88 binary-arch debian/rules target, and the architecture independent packages
  89 in the binary-indep debian/rules target.
  90
  91 To faciliatate this, as well as give you more control over which packages
  92 are acted on by debhelper programs, all debhelper programs accept the
  93 following parameters:
  94
  95 -a              Act on architecture dependent packages
  96 -i              Act on architecture independent packages
  97 -ppackage       Act on the package named "package" (may be repeated multiple
  98                 times)
  99
 100 These parameters are cumulative. If none are given, the tools default to
 101 effecting all packages.
 102
 103 See examples/rules.multi for an example of how to use this.
 104
 105 -- Joey Hess <joeyh@master.debian.org>