summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--Debian/Debhelper/Dh_Lib.pm2
-rw-r--r--debhelper.1116
-rw-r--r--debian/changelog23
-rwxr-xr-xdebian/rules6
-rwxr-xr-xdh_movefiles2
-rw-r--r--dh_movefiles.12
-rw-r--r--doc/PROGRAMMING11
-rw-r--r--doc/README74
-rw-r--r--doc/TODO2
-rw-r--r--doc/v268
-rwxr-xr-xexamples/rules8
-rwxr-xr-xexamples/rules.indep8
-rwxr-xr-xexamples/rules.multi8
-rwxr-xr-xexamples/rules.multi25
14 files changed, 144 insertions, 191 deletions
diff --git a/Debian/Debhelper/Dh_Lib.pm b/Debian/Debhelper/Dh_Lib.pm
index 49d9d6d..92059da 100644
--- a/Debian/Debhelper/Dh_Lib.pm
+++ b/Debian/Debhelper/Dh_Lib.pm
@@ -15,7 +15,7 @@ use vars qw(@ISA @EXPORT %dh);
&xargs
%dh);
-my $max_compat=2;
+my $max_compat=3;
sub init {
# If DH_OPTIONS is set, prepend it @ARGV.
diff --git a/debhelper.1 b/debhelper.1
index 6ed7ef7..acb6a70 100644
--- a/debhelper.1
+++ b/debhelper.1
@@ -5,12 +5,30 @@ debhelper \- overview of the debhelper commands
.B dh_*
.I "[-v] [-a] [-i] [-s] [--no-act] [-ppackage] [-Npackage] [-Ptmpdir]"
.SH "DESCRIPTION"
-Debhelper is a collection of programs that can be used in debian/rules files
-to automate common tasks related to building debian binary packages. All the
-debhelper commands accept a set of options, and this man page is here to
-document those options and to document debhelper as a whole. For additional
-options, and documentation for each individual command, see the commands' own
-man pages.
+Debhelper is used to help you build a debian package. The philospohy behind
+debhelper is to provide a collection of small, simple, and easily
+understood tools that are used in debian/rules to automate various common
+aspects of building a package. This means less work for you, the packager.
+It also, to some degree means that these tools can be changed if debian
+policy changes, and packages that use them will require only a rebuild to
+comply with the new policy.
+.P
+A typical debian/rules file that uses debhelper will call several debhelper
+commands in sequence. Debhelper commands are all named with a "dh_" prefix.
+Examples of rules files that use debhelper are in
+/usr/share/doc/debhelper/examples/ .
+.P
+To create a new debian package using debhelper, you can just copy one of
+the sample rules files and edit it by hand. Or you can try the dh-make
+package, which contains a
+.BR dh_make (1)
+command that partially automates the process. For a more gentle
+introduction, the maint-guide debian package contains a
+tutorial about making your first package using debhelper.
+.SH "DEBHELPER COMMANDS"
+Here is the complete list of available debhelper commands. See their man
+pages for additional documentation.
+#LIST#
.SH "SHARED DEBHLPER OPTIONS"
The following command line options are supported by all debhelper programs.
.TP
@@ -44,10 +62,10 @@ Do not act on the specified package even if an -a, -i, or -p option lists
the package as one that should be acted on.
.TP
.B \-Ptmpdir, \--tmpdir=tmpdir
-Use "tmpdir" for package build directory.
+Use "tmpdir" for package build directory. The default is debian/<package>
.SH "COMMON DEBHELPER OPTIONS"
The following command line options are supported by some debhelper programs.
-See the man page of each program for a complete explination of what the
+See the man page of each program for a complete explanation of what the
option does.
.TP
.B \-n
@@ -89,13 +107,32 @@ See
for an example of how to use this.
.RE
.TP
+.B Automatic generation of debian install scripts
+.RS
+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.
+.P
+All scripts that automatically generate code in this way let it be disabled
+by the -n parameter (see above).
+.P
+Note that the inserted code 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';
+ #DEBHELPER#
+ EOF
+ system ($temp) / 256 == 0
+ or die "Problem with debhelper scripts: $!";
+.RE
+.TP
.B Package build directories
.RS
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. If DH_COMPAT=2, debian/<packagename> is always used,
-even for the first package.
+for assembling the tree of files in a package is debian/<packagename>.
.P
Sometimes, you might want to use some other temporary directory. This is
supported by the
@@ -107,27 +144,61 @@ many binary packages, you will need to use the -p flag to specify which
binary package the debhelper program will act on.
.RE
.TP
+.B Debhelper compatability levels
+.RS
+From time to time, major non-backwards-compatabile changes need to be made
+to debhelper, to keep it clean and well-designed as needs change and its
+author gains more experience. To prevent such major changes from breaking
+existing packages, the DH_COMPAT environment variable was introduced.
+DH_COMPAT may be set to a number, to determine which major revision of
+debhelper should be used. There are currently 3:
+.TP
+.B V1
+Setting DH_COMPAT=1 (or leaving it unset) causes debhelper to act in
+compatability mode. It will use debian/tmp as the package tree
+directory for the first binary package listed in the control file, while using
+debian/<package> for all other packages listed in the control file.
+This mode is deprecated.
+.TP
+.B V2
+Setting DH_COMPAT=2 causes debhelper to consitently use debian/<package>
+as the package tree directory for every package that is built. This
+mode is currently set by default in all the example rules files, and you
+are encouraged to use it.
+.TP
+.B V3
+Setting DH_COMPAT=3 will make debhelper start using new v3 features as
+they are implemented. This will cause its behavior to change without
+notice, and so may break packages that use it. See the file
+"/usr/share/doc/debhelper/v3" for more information about planned
+changes.
+.RE
+.TP
.B Other notes
+.RS
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/<foo>/DEBIAN/
before trying to put files there, dh_installmenu knows you need a
debian/<foo>/usr/lib/menu/ before installing the menu files, etc.
-.SH "DEBHELPER COMMANDS"
-Here is the complete list of available debhelper commands.
-#LIST#
+.P
+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 the example rules file
+"rules.multi" by calling dh_movefiles in the install target.
+.P
+Once your package uses debhelper to build, be sure to add
+debhelper to your Build-Depends line in debian/control.
+.RE
.SH ENVIRONMENT
.TP
.I DH_VERBOSE
Enables verbose mode.
.TP
.I DH_COMPAT
-Specifies what compatability level debhelper should run at. The default is 1,
-which makes debhelper behave in a manner compatable with the 1.x series of
-debhelper. If set to 2, debhelper's behavior will change to use the new
-features of the 2.x series. Use this with caution, as the 2.x series makes
-major changes that will break most packages. For documentation on these
-changes, read /usr/share/doc/debhelper/v2
+Specifies what compatability level debhelper should run at. See above.
.TP
.I DH_NO_ACT
Enables no-act mode.
@@ -142,9 +213,6 @@ good way to set DH_OPTIONS is by using "Target-specific Variable Values" in
your debian/rules file. See the make documentation for details on doing this.
.SH "SEE ALSO"
.TP
-.BR /usr/share/doc/debhelper/README
-An introduction to debhelper.
-.TP
.BR /usr/share/doc/debhelper/examples/
A set of example debian/rules files that use debhelper.
.TP
diff --git a/debian/changelog b/debian/changelog
index d02b02f..9b78bc9 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,26 @@
+debhelper (2.1.0) unstable; urgency=low
+
+ * 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).
+
+ -- Joey Hess <joeyh@debian.org> Tue, 18 Jul 2000 15:48:41 -0700
+
debhelper (2.0.104) unstable; urgency=low
* Put dh_installogrotate in the examples, Closes: #66986
diff --git a/debian/rules b/debian/rules
index a677cff..225db74 100755
--- a/debian/rules
+++ b/debian/rules
@@ -6,12 +6,16 @@
# to tell you that; just see the 25 lines of inlined perl below..
# See examples/ for some good examples.
+# Ensure that builds are self-hosting, which means I have to use the .pm
+# files in this package, not any that may be on the system.
+export PERL5LIB=.
+
# If any automatic script generation is done in building this package,
# be sure to use the new templates from this package.
export DH_AUTOSCRIPTDIR=autoscripts
# Living dangerously :-)
-export DH_COMPAT=2
+export DH_COMPAT=3
# Figure out the current debhelper version.
VERSION=$(shell expr "`dpkg-parsechangelog 2>/dev/null |grep Version:`" : '.*Version: \(.*\)')
diff --git a/dh_movefiles b/dh_movefiles
index bf1fa66..ad9add2 100755
--- a/dh_movefiles
+++ b/dh_movefiles
@@ -37,7 +37,7 @@ foreach $PACKAGE (@{$dh{DOPACKAGES}}) {
}
if (@tomove && $TMP eq $sourcedir) {
- error("I was asked to move files from $sourcedir to $sourcedir.");
+ error("I was asked to move files from $sourcedir to $sourcedir. Perhaps you should set DH_COMAPT=2?");
}
if (@tomove) {
diff --git a/dh_movefiles.1 b/dh_movefiles.1
index 10277c6..645e826 100644
--- a/dh_movefiles.1
+++ b/dh_movefiles.1
@@ -28,7 +28,7 @@ See
for a list of options common to all debhelper commands.
.TP
.B --sourcedir=dir
-Instead of moveing files out of debian/tmp (the default), this option makes
+Instead of moving files out of debian/tmp (the default), this option makes
it move files out of some other directory. Since the entire contents of
the sourcedir is moved, specifiying something like --sourcedir=/ is very
unsafe, so to prevent mistakes, the sourcedir must be a relative filename; it
diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING
index df9a728..ca10ca3 100644
--- a/doc/PROGRAMMING
+++ b/doc/PROGRAMMING
@@ -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()
tmpdir()
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".
compat()
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
-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 (note that I made sure that $1, $2, etc are set with the set command):
-
-my $temp="set -e\nset -- @ARGV\n" . << 'EOF';
-#DEBHELPER#
-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 http://kitenet.net/programs/debhelper/
-
--- Joey Hess <joeyh@debian.org>
+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
-them.
-
-+ 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 xbar.man
- dh_installmanpages --section=8 su.man
- 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.
-
diff --git a/examples/rules b/examples/rules
index a59c98c..19b5777 100755
--- a/examples/rules
+++ b/examples/rules
@@ -6,7 +6,7 @@
#export DH_VERBOSE=1
# This is the debhelper compatibility version to use.
-export DH_COMPAT=1
+export DH_COMPAT=2
build: build-stamp
build-stamp:
@@ -34,8 +34,8 @@ install: build
dh_clean -k
dh_installdirs
- # Add here commands to install the package into debian/tmp.
- #$(MAKE) prefix=`pwd`/debian/tmp/usr install
+ # Add here commands to install the package into debian/<packagename>
+ #$(MAKE) prefix=`pwd`/debian/`dh_listpackages`/usr install
# Build architecture-independent files here.
binary-indep: build install
@@ -43,7 +43,7 @@ binary-indep: build install
# Build architecture-dependent files here.
binary-arch: build install
-# dh_testversion
+ dh_testversion 2
dh_testdir
dh_testroot
# dh_installdebconf
diff --git a/examples/rules.indep b/examples/rules.indep
index 694b53a..0c3e6e1 100755
--- a/examples/rules.indep
+++ b/examples/rules.indep
@@ -8,7 +8,7 @@
#export DH_VERBOSE=1
# This is the debhelper compatibility version to use.
-export DH_COMPAT=1
+export DH_COMPAT=2
build: build-stamp
build-stamp:
@@ -36,12 +36,12 @@ install: build
dh_clean -k
dh_installdirs
- # Add here commands to install the package into debian/tmp.
- #$(MAKE) prefix=`pwd`/debian/tmp/usr install
+ # Add here commands to install the package into debian/<packagename>.
+ #$(MAKE) prefix=`pwd`/debian/`dh_listpackages`/usr install
# Build architecture-independent files here.
binary-indep: build install
-# dh_testversion
+ dh_testversion 2
dh_testdir
dh_testroot
# dh_installdebconf
diff --git a/examples/rules.multi b/examples/rules.multi
index 8c79626..3ac7a03 100755
--- a/examples/rules.multi
+++ b/examples/rules.multi
@@ -10,7 +10,7 @@
#export DH_VERBOSE=1
# This is the debhelper compatibility version to use.
-export DH_COMPAT=1
+export DH_COMPAT=2
# This has to be exported to make some magic below work.
export DH_OPTIONS
@@ -51,8 +51,7 @@ install: build
# Pass -i to all debhelper commands in this target to reduce clutter.
binary-indep: DH_OPTIONS=-i
binary-indep: build install
- # Need this version of debhelper for DH_OPTIONS to work.
- dh_testversion 1.1.17
+ dh_testversion 2
dh_testdir
dh_testroot
# dh_installdebconf
@@ -84,8 +83,7 @@ binary-indep: build install
# Pass -a to all debhelper commands in this target to reduce clutter.
binary-arch: DH_OPTIONS=-a
binary-arch: build install
- # Need this version of debhelper for DH_OPTIONS to work.
- dh_testversion 1.1.17
+ dh_testversion 2
dh_testdir
dh_testroot
# dh_installdebconf
diff --git a/examples/rules.multi2 b/examples/rules.multi2
index 3dbc0f5..0af60ee 100755
--- a/examples/rules.multi2
+++ b/examples/rules.multi2
@@ -9,7 +9,7 @@
#export DH_VERBOSE=1
# This is the debhelper compatibility version to use.
-export DH_COMPAT=1
+export DH_COMPAT=2
# This has to be exported to make some magic below work.
export DH_OPTIONS
@@ -51,8 +51,7 @@ install: build
# affect _all_ packages. Anything you want to only affect one package
# should be put in another target, such as the install target.
binary-common:
- # Need this version of debhelper for DH_OPTIONS to work.
- dh_testversion 1.1.17
+ dh_testversion 2
dh_testdir
dh_testroot
# dh_installdebconf