From d24f48c801b705fe7b95f27250cfe52d8e3e7319 Mon Sep 17 00:00:00 2001 From: joey Date: Tue, 17 Aug 1999 04:51:05 +0000 Subject: r84: Initial revision --- doc/README | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 doc/README (limited to 'doc/README') diff --git a/doc/README b/doc/README new file mode 100644 index 00000000..986eb02c --- /dev/null +++ b/doc/README @@ -0,0 +1,100 @@ +Debhelper is a collection of programs that can be used in debian/rules files +to automate common tasks. For further documentation, see the man pages for +dh_* commands. + +To help you get started, I've included examples of debian/rules files +that use debhelper commands extensively. See /usr/doc/debhelper/examples/ . +These files are also useful as they give one good order you can run the +various debhelper scripts in (though other variations are possible). + +Starting a new package: +---------------------- + +You can just use the example rules files and do the rest of the new package +set up by hand, or you could try the new dh-make package, which contains a +"dh_make" command that is similar to debmake, and tries to automate the +process. + +Converting from debstd to debhelper: +----------------------------------- + +See the file "from-debstd" for documentation on how to do this. + +Automatic generation of debian install scripts: +---------------------------------------------- + +Some debhelper commands will automatically generate parts of debian install +scripts. If you want these automatically generated things included in your +debian install scripts, then you need to add "#DEBHELPER#" to your scripts, +in the place the code should be added. "#DEBHELPER#" will be replaced by any +auto-generated code when you run dh_installdeb. + +All scripts that automatically generate code in this way let it be disabled +by the -n parameter. + +Note that it will be shell code, so you cannot directly use it in a perl +script. If you would like to embed it into a perl script, here is one way to +do that: + +print << `EOF` +#DEBHELPER# +EOF + + +Notes on multiple binary packages: +--------------------------------- + +If your source package generates more than one binary package, debhelper +programs will default to acting on all binary packages when run. If your +source package happens to generate one architecture dependent package, and +another architecture independent package, this is not the correct behavior, +because you need to generate the architecture dependent packages in the +binary-arch debian/rules target, and the architecture independent packages +in the binary-indep debian/rules target. + +To facilitate this, as well as give you more control over which packages +are acted on by debhelper programs, all debhelper programs accept the +following parameters: + +-a Act on architecture dependent packages +-i Act on architecture independent packages +-ppackage Act on the package named "package" (may be repeated multiple + times) + +These parameters are cumulative. If none are given, the tools default to +affecting all packages. + +See examples/rules.multi for an example of how to use this. + +Package build directories -- debian/tmp, etc: +-------------------------------------------- + +By default, all debhelper programs assume that the temporary directory used +for assembling the tree of files in a package is debian/tmp for the first +package listed in debian/control, and debian/ for each +additional package. + +Sometimes, you might want to use some other temporary directory. This is +supported by the -P flag. The directory to use is specified after -P, for +example, "dh_installdocs -Pdebian/tmp", will use debian/tmp as the temporary +directory. Note that if you use -P, the debhelper programs can only be +acting on a single package at a time. So if you have a package that builds +many binary packages, you will need to use the -p flag to specify which +binary package the debhelper program will act on. For example: + + dh_installdocs -pfoolib1 -Pdebian/tmp-foolib1 + dh_installdocs -pfoolib1-dev -Pdebian/tmp-foolib1-dev + dh_installdocs -pfoolib-bin -Pdebian/tmp-foolib-bin + +This uses debian/tmp- as the package build directory. + +Other notes: +----------- + +* In general, if any debhelper program needs a directory to exist under + debian/, it will create it. I haven't bothered to document this in all the + man pages, but for example, dh_installdeb knows to make debian/tmp/DEBIAN/ + before trying to put files there, dh_installmenu knows you need a + debian/tmp/usr/lib/menu/ before installing the menu files, etc. + +-- Joey Hess -- cgit v1.2.3