diff options
| -rw-r--r-- | Debian/Debhelper/Dh_Lib.pm | 2 | ||||
| -rw-r--r-- | debhelper.1 | 116 | ||||
| -rw-r--r-- | debian/changelog | 23 | ||||
| -rwxr-xr-x | debian/rules | 6 | ||||
| -rwxr-xr-x | dh_movefiles | 2 | ||||
| -rw-r--r-- | dh_movefiles.1 | 2 | ||||
| -rw-r--r-- | doc/PROGRAMMING | 11 | ||||
| -rw-r--r-- | doc/README | 74 | ||||
| -rw-r--r-- | doc/TODO | 2 | ||||
| -rw-r--r-- | doc/v2 | 68 | ||||
| -rwxr-xr-x | examples/rules | 8 | ||||
| -rwxr-xr-x | examples/rules.indep | 8 | ||||
| -rwxr-xr-x | examples/rules.multi | 8 | ||||
| -rwxr-xr-x | examples/rules.multi2 | 5 |
14 files changed, 144 insertions, 191 deletions
diff --git a/Debian/Debhelper/Dh_Lib.pm b/Debian/Debhelper/Dh_Lib.pm index 49d9d6d0..92059daa 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 6ed7ef7a..acb6a705 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 d02b02f9..9b78bc95 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 a677cff3..225db74c 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 bf1fa667..ad9add28 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 10277c6a..645e8263 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 df9a7287..ca10ca38 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 @@ -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. @@ -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 327e625e..00000000 --- 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 a59c98cf..19b5777a 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 694b53ae..0c3e6e15 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 8c79626d..3ac7a030 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 3dbc0f52..0af60eea 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 |