From a7afc7fccd48b73037a32e511a219016ba9fee17 Mon Sep 17 00:00:00 2001 From: joey Date: Wed, 19 Jul 2000 00:33:24 +0000 Subject: 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/ 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). --- Debian/Debhelper/Dh_Lib.pm | 2 +- debhelper.1 | 116 +++++++++++++++++++++++++++++++++++---------- debian/changelog | 23 +++++++++ debian/rules | 6 ++- dh_movefiles | 2 +- dh_movefiles.1 | 2 +- doc/PROGRAMMING | 11 ++--- doc/README | 74 +---------------------------- doc/TODO | 2 + doc/v2 | 68 -------------------------- examples/rules | 8 ++-- examples/rules.indep | 8 ++-- examples/rules.multi | 8 ++-- examples/rules.multi2 | 5 +- 14 files changed, 144 insertions(+), 191 deletions(-) delete mode 100644 doc/v2 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/ .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/ for each -additional package. If DH_COMPAT=2, debian/ is always used, -even for the first package. +for assembling the tree of files in a package is debian/. .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/ 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/ +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//DEBIAN/ before trying to put files there, dh_installmenu knows you need a debian//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/ 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 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 diff --git a/doc/README b/doc/README index 93351579..6ae07976 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 +Please see the debhelper(1) man page for documentation. diff --git a/doc/TODO b/doc/TODO index 246b2a6f..d16c7804 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 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// for other packages of a multi-binary package. I've - decided after much agonizing to to use debian/. 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/ for making most of - thier .deb's anyway. I eliminated the other ideas for these reasons: - - debian/tmp/: debian/tmp already has history behind it, - changing how it's used would be confusing. - - debian/build/: confusing (is the code compiled there?) - - debian/tmp-, debian/package-: 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/.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/.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//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//* 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/ works, and will deprecate that usage. - debian/. 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/ + #$(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/. + #$(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 -- cgit v1.2.3