to automate common tasks. For further documentation, see the man pages for
dh_* commands.
-To help you get started, I've included an example of a debian/rules file
-that uses debhelper commands extensivly. See
-/usr/doc/debhelper/examples/rules . These files are also useful as they give
-one good order you can run the different debhelper scripts in (though other
-variations are possible).
+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:
-----------------------------------
-Debhelper is designed to be mostly backwards compatable to debstd. I say
-mostly becuase I haven't made debhelper handle everything that debstd does
-yet, and in a few cases, it does things differently (and I hope, better).
-
-In general, you can switch over to using debhelper as follows. In your
-debian/rules, where you used to have some lines that read something like:
-
- debstd CHANGES TODO README
- dpkg-gencontrol
- dpkg --build debian/tmp ..
-
-Remove that and replace it with something like:
-
- dh_installdocs TODO README
- dh_installexamples
- dh_installmenu
- dh_installcron
- dh_installmanpages
- dh_installchangelogs CHANGES
- dh_strip
- dh_compress
- dh_fixperms
- dh_suidregister
- dh_installdebfiles
- dh_makeshlibs
- dh_md5sums
- dh_builddeb
-
-Notice that the parameters sent to debstd get split up among the dh_*
-programs. The upstream changelog is passed to dh_installchangelogs, and the
-docs are passed to dh_installdocs.
-
-Debstd has many switches, that turn off differnt parts of it. So if you
-were using debstd -m to tell it not to automatically install manpages,
-for example, you can just comment out the dh_installmanpages line.
-
-Finally, debstd automatically modified postinst, postrm, etc scripts. Some
-of the dehelper apps do that too, but they do it differnently. Debstd just
-appends its commands to the end of the script. Debhelper reqyires that you
-insert a tag into your scripts, that will tell debhelper where to insert
-commands. So if you have postinst, postrm, etc scripts, add a line reading
-"#DEBHELPER" to the end of them.
-
-Once you think it's all set up properly, do a test build of your package. If
-it works ok, I reccommend that you compare the new package and the old
-debstd-generated package very closely. Pay special attention to the postint,
-postrm, etc scripts.
-
+See the file "from-debstd" for documentation on how to do this.
Automatic generation of debian install scripts:
----------------------------------------------
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
-autogenerated code when you run dh_installdebfiles.
+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.
+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:
binary-arch debian/rules target, and the architecture independent packages
in the binary-indep debian/rules target.
-To faciliatate this, as well as give you more control over which packages
+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:
times)
These parameters are cumulative. If none are given, the tools default to
-effecting all packages.
+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>