summaryrefslogtreecommitdiff
path: root/doc/README
diff options
context:
space:
mode:
authorjoey <joey>1999-08-17 04:51:05 +0000
committerjoey <joey>1999-08-17 04:51:05 +0000
commitd24f48c801b705fe7b95f27250cfe52d8e3e7319 (patch)
tree201e2359785f0d4a37355e1f8b680d59218744ba /doc/README
parent26ee9ad04424bc35ba9c1bbc3b062d6d339bbebd (diff)
r84: Initial revision
Diffstat (limited to 'doc/README')
-rw-r--r--doc/README100
1 files changed, 100 insertions, 0 deletions
diff --git a/doc/README b/doc/README
new file mode 100644
index 0000000..986eb02
--- /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/<packagename> 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-<package> 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 <joeyh@master.debian.org>