diff options
| -rw-r--r-- | .foo | 0 | ||||
| -rw-r--r-- | BUGS | 0 | ||||
| -rw-r--r-- | doc/PROGRAMMING | 204 | ||||
| -rw-r--r-- | doc/README | 70 | ||||
| -rw-r--r-- | doc/TODO | 56 | ||||
| -rw-r--r-- | doc/from-debstd | 63 | ||||
| -rw-r--r-- | doc/v2 | 64 | ||||
| -rw-r--r-- | foo | 2 |
8 files changed, 0 insertions, 459 deletions
diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING deleted file mode 100644 index 891d31b0..00000000 --- a/doc/PROGRAMMING +++ /dev/null @@ -1,204 +0,0 @@ -This file documents things you should know to write a new debhelper program. - -Standardization: ---------------- - -There are lots of debhelper commands. To make the learning curve shallower, -I want them all to behave in a standard manner: - -All debhelper programs have names beginning with "dh_". This is so we don't -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. - -Debhelper programs should accept the options, -v, -i, -a, -p, --no-act, and --P, and any long forms of these options, like --verbose . If necessary, the -options may be ignored. - -If debhelper commands need config files, they should use -debian/package.filename as the name of the config file (replace filename -with whatever your command wants), and debian/filename should also be -checked for config information for the first binary package in -debian/control. Also, debhelper commands should accept the same sort of -information that appears in the config files, on their command lines, if -possible, and apply that information to the first package they act on. - -Debhelper programs should never modify the debian/postinst, debian/prerm, -etc scripts, instead, they can add lines to debian/postinst.debhelper, etc. -The autoscript() function (see below) is one easy way to do this. -dh_installdeb is an exception, it will run after the other commands and -merge these modifications into the actual postinst scripts. - -There are always exceptions. Just ask me. - -Introducing Dh_Lib.pm: ---------------------- - -Dh_lib.pm is the library used by all debhelper programs to parse their -arguments and set some useful variables. It's not mandatory that your -program use Dh_lib.pm, but it will make it a lot easier to keep it in sync -with the rest of debhelper if it does, so this is highly encouraged. - -(There used to be a version of Dh_lib.pm that was a library of functions for -shell scripts. If you want to write a debhelper command that is a shell -script, I can dig up that old library for you. Only the perl one is -supported now, though.) - -Use Dh_lib.pm like this: - -BEGIN { push @INC, "debian", "/usr/share/debhelper" } -use Dh_Lib; -init(); - -The BEGIN block is there to make perl look for the module in all the right -places. - -The init() function in the perl version. This causes Dh_lib to -parse the command line and do some other initialization tasks. - -Argument processing: -------------------- - -All debhelper programs should respond to certain arguments, such as -v, -i, --a, and -p. To help you make this work right, Dh_Lib.pm handles argument -processing. Just call init(). - -After argument processing, some global variables are used to hold the -results; programs can use them later. These variables are elements of the -%dh hash. - -switch variable description --v VERBOSE should the program verbosely output what it is - doing? ---no-act NO_ACT should the program not actually do anything? --i,-a,-p,-N DOPACKAGES a space delimited list of the binary packages - to act on (in Dh_Lib.pm, this is an array) --i,-p,-N DOINDEP a space delimited list of the binary independent - packages to act on --a,-p,-N DOARCH a space delimited list of the binary dependent - packages to act on --n NOSCRIPTS if set, do not make any modifications to the - package's postinst, postrm, etc scripts. --X EXCLUDE exclude a something from processing (you - decide what this means for your program) - (This is an array) - EXCLUDE_FIND same as DH_EXCLUDE, except all items are put - into a string in a way that they will make - find find them. (Use ! in front to negate - that, of course) --x INCLUDE_CONFFILES - include conffiles. It's -x for obscure - historical reasons. --d D_FLAG you decide what this means to your program --r R_FLAG you decide what this means to your program --k K_FLAG you decide what this means to your program --P TMPDIR package build directory (implies only one - package is being acted on) --u U_PARAMS will be set to a string, that is typically - parameters your program passes on to some - other program. (This is an array) --m M_PARAMS will be set to a string, you decide what it - means to your program --V V_FLAG will be set to a string, you decide what it - means to your program --V V_FLAG_SET will be 1 if -V was specified, even if no - parameters were passed along with the -V --A PARAMS_ALL generally means that additional command line - parameters passed to the program (other than - those processed here), will apply to all - binary packages the program acts on, not just - the first ---init-script INIT_SCRIPT will be set to a string, which specifies an - init script name (probably only - dh_installinit will ever use this) ---sourcedir SOURCEDIR will be set to a string (probably only - dh_movefiles will ever use this) ---destdir DESTDIR will be set to a string (probably only - dh_builddeb will ever use this) ---flavor FLAVOR will be set to a string (probably only - dh_installemacsen will ever use this) ---number NUMBER will be set to a number - -Any additional command line parameters that do not start with "-" will be -ignored, and you can access them later just as you normally would. - -If you need a new command line option, just ask me, and I will add it. - -Global variables: ----------------- - -The following keys are also set in the %dh hash when you call init(): - -MAINPACKAGE the name of the first binary package listed in - debian/control -FIRSTPACKAGE the first package we were instructed to act on. This package - typically gets special treatment, additional arguments - specified on the command line may effect it. - -Functions: ---------- - -Dh_Lib.pm also contains a number of functions you may find useful. - -doit() - Pass this function an array that is a - shell command. It will run the command (unless $dh{NO_ACT} is set), and - if $dh{VERBOSE} is set, it will also output the command to stdout. You - should use this function for almost all commands your program performs - that manipulate files in the package build directories. -complex_doit() - Pass this function a string that is a shell command, it will run it - similarly to how doit() does. You can pass more complicated commands - to this (ie, commands involving piping redirection), however, you - have to worry about things like escaping shell metacharacters. -verbose_print() - Pass this command a string, and it will echo it if $dh{VERBOSE} is set. -error() - Pass this command a string, it will output it to standard error and - exit. -warning() - Pass this command a string, and it will output it to standard error - as a warning message. -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". -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 - the compatability level. -pkgfile() - Pass this command the name of a binary package, and the base name of a - file, and it will return the actual filename to use. This is used - for allowing debhelper programs to have configuration files in the - debian/ directory, so there can be one config file per binary - package. The convention is that the files are named - debian/package.filename, and debian/filename is also allowable for - the $dh{MAINPACKAGE}. If the file does not exist, nothing is returned. -pkgext() - Pass this command the name of a binary package, and it will return - the name to prefix to files in debian/ for this package. For the - $dh{MAINPACKAGE}, it returns nothing (there is no prefix), for the other - packages, it returns "package.". -isnative() - Pass this command the name of a package, it returns 1 if the package - is a native debian package. - As a side effect, $dh{VERSION} is set to the version number of the - package. -autoscript() - Pass parameters: - - binary package to be affected - - script to add to - - filename of snippet - - sed commands to run on the snippet. Ie, s/#PACKAGE#/$PACKAGE/ - (optional) - This command automatically adds shell script snippets to a debian - maintainer script (like the postinst or prerm). - --- Joey Hess <joeyh@master.debian.org> diff --git a/doc/README b/doc/README deleted file mode 100644 index ff43553e..00000000 --- a/doc/README +++ /dev/null @@ -1,70 +0,0 @@ -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/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. - -Debhelper's home page is at http://kitenet.net/programs/debhelper/ - --- Joey Hess <joeyh@master.debian.org> diff --git a/doc/TODO b/doc/TODO deleted file mode 100644 index e3b999bc..00000000 --- a/doc/TODO +++ /dev/null @@ -1,56 +0,0 @@ -This is the TODO for debhelper. As more and more people use debhelper, this -list grows - I welcome patches to fix items on it! - -Wishlist items: - -* Make dh_* "use strict". -* Make dh_movefiles remove emptied directories after it's moved all the - files out of them (#17111). -* enhance dh_installmanpages so it associates binaries and man pages and - installs the man pages into the correct areas to suit the binaries they - document. I may need to make this only happen when a switch is given, to - preserve backward compatibility. (#16933, #17061) -* maybe make dh_installmanpages look at the .TH line of man pages whose - filenames end in .man, to figure out what section they go it. This would - require a switch to turn on, for backwards compatibility. -* All debhelper programs should be checked that they output files with the - correct permissions no matter what the umask is set to. Currently, only - those programs that run after dh_fixperms have been so checked. (Checking - the rest is low priority, since dh_fixperms fixes any incorrect permissions - they might have; still it would be nice to check them too, just to make - debhelper more flexible.) One easy fix is to add umask 022 to dh_lib, - however, there may be unforeseen ramifications of such a change. -* All programs should also make sure the files they install are owned by - root.root. Situation is currently the same as with permissions above, plus - dh_installchangelogs is fixed. -* something should add ldconfig calls properly to the postinst of packages - that contain shared libraries. maybe dh_makeshlibs? But it wasn't designed - to do that originally, and even worse, it is often run after - dh_installdeb, so the fragments wouldn't go into the postinst. So maybe a - new script is called for. But it's probably be best to just have a switch - to enable this. -* Need a way to make dh_strip not strip any static libs. Also, it'd be nice - if there were options to dh_strip, dh_compress, etc, to allow inclusion of - directories and exclusion of files based on filename globbing. (Request from - Matthias Klose <doko@cs.tu-berlin.de>) -* Support use of environment variables in data taken from user, ie, in - debian/dirs. The problem with doing this is that we really want to allow - any filenames in that input, even those that look like environment - variables. However, it may be worth adding a switch to make it parse - environment variables. (#20964) -* It's possible to speed up debhelper by having it cache some values that - multiple commands call. One way to do this would be to write dh_cache, - that generates the cache. The catch is that if the user runs that program, - they are stating that they don't do anything later to invalidate the cache, - without calling ch_cache again. (#23792) -* Add a switch to dh_installdeb to allow it to do user defined - substitutions. OTOH, maybe it's better if people just sed - postinst.in before debhelper gets it's hands on it... (#25235) - -Deprecated: - -* remove dh_installdebfiles, dh_du. - - need to wait a reasonable length of - time. I'm currently planning on doing this after slink is released or - one year after they were deprecated, whichever comes first. Be sure to - grep whole debian archive for all of them before removing them, though! diff --git a/doc/from-debstd b/doc/from-debstd deleted file mode 100644 index 86f29dce..00000000 --- a/doc/from-debstd +++ /dev/null @@ -1,63 +0,0 @@ -Converting from debstd to debhelper: ------------------------------------ - -Debhelper is designed to be mostly backwards compatible to debstd. I say -mostly because I haven't made debhelper handle everything that debstd does -yet, and in a few cases, debhelper does things differently (and I hope, -better). - -In general, you can switch over to using debhelper as follows. In your -debian/rules, you currently will have some lines that read something like -this: - - debstd CHANGES TODO README - dpkg-gencontrol - dpkg --build debian/tmp .. - -Debhelper comes with a command called dh_debstd that mimics the behavior of -debstd, by calling various debhelper commands. So in the root directory of -your package you are converting, run: - - dh_debstd CHANGES TODO README --verbose --no-act - -Notice the parallel to the debstd command above, I just added -"--verbose --noact" to the end. This will make dh_debstd output a list of -commands that it thinks will emulate what debstd would have done, without -actually doing anything to your package. The list will look similar to this: - - dh_installdirs - dh_installdocs TODO README - dh_installexamples - dh_installchangelogs CHANGES - dh_installmenu - dh_installcron - dh_installmanpages - dh_movefiles - dh_strip - dh_compress - dh_fixperms - dh_suidregister - dh_shlibdeps - dh_gencontrol - dh_makeshlibs - dh_installdeb - dh_md5sums - dh_builddeb - -Now copy that output into debian/rules, replacing the debstd command, as -well as any dpkg-gencontrol and dpkg --build commands. - -Finally, debstd automatically modified postinst, postrm, etc scripts. Some -of the debhelper apps do that too, but they do it differently. Debstd just -appends its commands to the end of the script. Debhelper requires 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 recommend that you compare the new package and the old -debstd-generated package very closely. Pay special attention to the -postinst, postrm, etc scripts, and make sure that the new package contains -all the same files as the old, with the same permissions. - --- Joey Hess <joeyh@master.debian.org> diff --git a/doc/v2 b/doc/v2 deleted file mode 100644 index b120d036..00000000 --- a/doc/v2 +++ /dev/null @@ -1,64 +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 extention, 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/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. @@ -1,2 +0,0 @@ -x="debian|autoscripts" -find |grep -F "`echo "$x" | tr "|" "\n"`"
\ No newline at end of file |