path: root/doc
diff options
authorjoey <joey>2000-07-19 00:33:24 +0000
committerjoey <joey>2000-07-19 00:33:24 +0000
commita7afc7fccd48b73037a32e511a219016ba9fee17 (patch)
treeae8ddff5a61ce11e724e0d79fa2d2ce8f7114a71 /doc
parent23098f605ed8cb77509f34f2deb131c18b357c05 (diff)
r359: * I started work on debhelper v2 over a year ago, with a long list of
changes I hoped to get in that broke backwards compatability. That development stalled after only the most important change was made, although I did get out over 100 releases in the debhelper 2.0.x tree. In the meantime, lots of packages have switched to using v2, despite my warnings that doing so leaves packages open to being broken without notice until v2 is complete. * Therefore, I am calling v2 complete, as it is. Future non-compatabile changes will happen in v3, which will be started soon. This means that by using debhelper v2, one major thing changes: debhelper uses debian/<package> as the temporary directory for *all* packages; debian/tmp is no longer used to build binary packages out of. This is very useful for multi-binary packages, and I reccommend everyone switch to v2. * Updated example rules files to use v2 by default. * Updated all documentation to assume that v2 is being used. * Added a few notes for people still using v1. * Moved all of the README into debhelper(1).
Diffstat (limited to 'doc')
4 files changed, 8 insertions, 147 deletions
diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index df9a728..ca10ca3 100644
@@ -11,10 +11,10 @@ pollute the name space too much.
Debhelper programs should never output anything to standard output except
error messages, important warnings, and the actual commands they run that
-modify files under debian/ and debian/tmp, etc (this last only if they are
-passed -v, and if you output the commands, you should indent them with 1 tab).
-This is so we don't have a lot of noise output when all the debhelper commands
-in a debian/rules are run, so the important stuff is clearly visible.
+modify files under debian/ (this last only if they are passed -v, and if you
+output the commands, you should indent them with 1 tab). This is so we don't
+have a lot of noise output when all the debhelper commands in a debian/rules
+are run, so the important stuff is clearly visible.
Debhelper programs should accept all options listed in the "SHARED
DEBHELPER OPTIONS" section of debhelper(1), including and any long forms of
@@ -171,8 +171,7 @@ warning()
Pass this command the name of a binary package, it will return the
name of the tmp directory that will be used as this package's
- package build directory. Typically, this will be "debian/tmp" or
- "debian/package".
+ package build directory. Typically, this will be "debian/package".
Pass this command a number, and if the current compatability level
equals that number, it will return true. Looks at DH_COMPAT to get
diff --git a/doc/README b/doc/README
index 9335157..6ae0797 100644
--- a/doc/README
+++ b/doc/README
@@ -1,74 +1,2 @@
-Debhelper is a collection of programs that can be used in debian/rules files
-to automate common tasks related to building debian binary packages. For
-further documentation, see the man pages for dh_* commands. For an overview
-of debhelper, including a list of all the available commands, see the
-debhelper(1) man page.
-To help you get started, I've included examples of debian/rules files
-that use debhelper commands extensively. See
-/usr/share/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).
-For a more gentle introduction, the maint-guide debian package contains a
-tutorial about making your first package using Debhelper.
-Debhelper v2:
-Debhelper v2 is a major new version of Debhelper, still under development.
-Debhelper will continue to work in v1 compatability mode for now, if you're
-interested in trying the new versiln, read the file named "v2".
-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 dh-make package, which contains a
-"dh_make" command that is similar to debmake, and tries to automate the
-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 (note that I made sure that $1, $2, etc are set with the set command):
-my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
-system ($temp) / 256 == 0
- or die "Problem with debhelper scripts: $!\n";
-Other notes:
-* Note that if you are generating a debian package that has arch-indep and
- arch-dependent portions, and you are using dh_movefiles to move the
- arch-indep files out of debian/tmp, you need to make sure that dh_movefiles
- does this even if only the arch-dependent package is being built (for ports
- to other architectures). I handle this in debian/rules.multi by calling
- dh_movefiles in the install target.
-* Once your package uses debhelper to build, be sure to add
- debhelper to your Build-Depends line in debian/control.
-* Debhelper's home page is at
--- Joey Hess <>
+Please see the debhelper(1) man page for documentation.
diff --git a/doc/TODO b/doc/TODO
index 246b2a6..d16c780 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -67,4 +67,6 @@ Deprecated:
- currently, a few packages in potato use dh_du, but bugs have been filed.
* Remove support for --number option
- only dh_installemacsen ever used it, it is not --priority.
+* DH_COMPAT 1. Can be removed onve all packages are seen to be using 2 or
+ higher. I won't hold my breath.
diff --git a/doc/v2 b/doc/v2
deleted file mode 100644
index 327e625..0000000
--- a/doc/v2
+++ /dev/null
@@ -1,68 +0,0 @@
-Debhelper v2 is a major new revision of debhelper. Currently, v2 is still
-being worked on, and will change in drastic ways without notice. To keep
-this from breaking packages, debhelper will continue to operate in v1
-compatability mode by default.
-To enable debhelper v2 features (do this with *caution*), set DH_COMPAT=2 in
-your debian/rules. Also, it is a very good idea to add a call to your
-debian/rules like this:
- dh_testversion 2
-To ensure that your package won't be built with some old version of
-debhelper that ignores the DH_COMPAT flag.
-Here are the changes I'm planning to make to debhelper for v2, based on
-prior discussion on debian-devel.
-Items marked with a + are done. All others will happen as soon as I can code
-+ Standardize on the name used for the temporary build directory of a
- package. Currently it's debian/tmp/ for the first package and
- debian/<package>/ for other packages of a multi-binary package. I've
- decided after much agonizing to to use debian/<package>. The main thing this
- has going for it is it means lots of multi-binary packages need only small
- alterations, since they already use debian/<package> for making most of
- thier .deb's anyway. I eliminated the other ideas for these reasons:
- - debian/tmp/<package>: debian/tmp already has history behind it,
- changing how it's used would be confusing.
- - debian/build/<package>: confusing (is the code compiled there?)
- - debian/tmp-<package>, debian/package-<tmp>: too long, little gain
-* dh_installmanpages will be made into a non-DWIM program, so you'll have to
- specify all man pages to install and possibly where to put them. This may
- look something like:
- dh_installmanpages -x xterm.1 xfoo.1
- dh_installmanpages --section=8
- Ok, there's a _little_ DWIM left in there, it'll be smart enough to munge
- the .man filenames properly. It'll probably just assume all man pages have
- an extension, and delete that extentation, and add the correct one.
-* dh_movefiles will use a name other than debian/<package>.files for the
- list of what to move, because it can't use debian/files for the first
- package, since that file is already used elsewhere. It'll use
- debian/<package>.move
-* dh_movefiles should delete empty directories after it's moved all files
- out of them. (#17111)
-* debian/README will be installed as /usr/share/doc/<package>/README in
- native packages, and as README.Debian in non-native packages. This is
- consistent with the handing of debian/TODO and debian/changelog. (#34628)
-* There will be no change to the names of debhelper config files used, I've
- decided against debian/<package>/* and the like, because although those
- subdirs do work, they're not allowed by the packaging manual, and they'd
- make source unpacking by hand a lot harder. I will leave these files
- completly as they are now. However, I will remove most of the language
- documenting that debian/<foo> works, and will deprecate that usage.
- debian/<package>.<foo> will be preferred even in single binary packages.
-* Every file in etc/ will be automatically be flagged as a conffile.
-* Debhelper config files will support globbing via * and ?, when
- appropriate. To turn this off and use those changarcters raw, just quote
- them.
-* dh_makeshlibs will generate autoscript fragments for ldconfig. This will
- require you call it before dh_installdeb, which isn't always done now.