diff options
| -rw-r--r-- | PROGRAMMING | 8 | ||||
| -rw-r--r-- | TODO | 3 | ||||
| -rw-r--r-- | debian/changelog | 8 | ||||
| -rwxr-xr-x | dh_compress | 46 | ||||
| -rw-r--r-- | dh_compress.1 | 9 | ||||
| -rwxr-xr-x | dh_debstd | 218 | ||||
| -rw-r--r-- | dh_debstd.1 | 72 | ||||
| -rwxr-xr-x | dh_getopt.pl | 17 | ||||
| -rwxr-xr-x | dh_md5sums | 2 | ||||
| -rw-r--r-- | doc/PROGRAMMING | 187 | ||||
| -rw-r--r-- | doc/README | 100 | ||||
| -rw-r--r-- | doc/TODO | 26 | ||||
| -rw-r--r-- | doc/from-debstd | 63 | ||||
| -rw-r--r-- | foo | 2 | ||||
| -rw-r--r-- | from-debstd | 63 |
15 files changed, 802 insertions, 22 deletions
diff --git a/PROGRAMMING b/PROGRAMMING index 22e015af..a6078c1a 100644 --- a/PROGRAMMING +++ b/PROGRAMMING @@ -76,8 +76,14 @@ switch variable description packages to act on -n DH_NOSCRIPTS if set, do not make any modifications to the package's postinst, postrm, etc scripts. --x DH_EXCLUDE exclude a something from processing (you +-X DH_EXCLUDE exclude a something from processing (you decide what this means for your program) + DH_EXCLUDE_GREP same as DH_EXCLUDE, except all items are + separated by '|' characters, instead of spaces, + handy for egrep -v +-x DH_INCLUDE_CONFFILES + include conffiles. It's -x for obscure + historical reasons. -d DH_D_FLAG you decide what this means to your program -r DH_R_FLAG you decide what this means to your program -k DH_K_FLAG you decide what this means to your program @@ -9,9 +9,6 @@ a -v switch, that lists all the other debhelper commands it needs to run to do what debstd had to do. The intent is to make it easy to switch from debstd to debhelper. -* dh_compress: add --exclude "*.conf" type-thingy, since that's the change - you most often want to make to what it does, and a debian/compress file is - overkill in those cases. * info support for debhelper (currently implemented, but I hate how I did it, so it's not in the package.) (wishlist bug #15717) * enhance dh_installmanpages so it associates binaries and man pages and diff --git a/debian/changelog b/debian/changelog index 148c6ea4..9d007f0f 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,11 @@ +debhelper (0.87) unstable; urgency=low + + * dh_strip: strip .comment and .note, not comment and note, when stripping + elf binaries. This makes for smaller output files. This has always been + broken in debhelper before! (#22395) + + -- Joey Hess <joeyh@master.debian.org> Wed, 13 May 1998 11:54:29 -0700 + debhelper (0.86) unstable; urgency=low * dh_compress: don't try to re-compress *.gz files. Eliminates warning diff --git a/dh_compress b/dh_compress index 27f931f5..1d30c65d 100755 --- a/dh_compress +++ b/dh_compress @@ -6,6 +6,32 @@ PATH=debian:$PATH:/usr/lib/debhelper . dh_lib +# Returns a list of all the files that we want to compress, +# (ignoring any files we were asked to exclude on the command +# line). Assummes we are already in the temp directory. +filelist () { + if [ "$compress" ]; then + # The config file is a sh script that outputs the files to be compressed + # (typically using find). + sh $olddir/$compress 2>/dev/null + else + # By default fall back on what the policy manual says to compress. + find usr/info usr/man usr/X11*/man -type f ! -name "*.gz" 2>/dev/null + find usr/doc -type f \( -size +4k -or -name "changelog*" \) \ + ! -name "*.htm*" ! -name "*.gif" ! -name "*.gz" \ + ! -name "copyright" 2>/dev/null + fi +} + +# Returns a list of all the files we want to compress, +# after taking command line exclusions into account. +# Call only if DH_EXCLUDE_GREP is non-empty. +filelist_excluded () { + # Use grep -F so we don't have to worry about regexp's. + filelist | grep -v -F \ + "`echo "$DH_EXCLUDE_GREP" | tr "|" "\n"`" +} + for PACKAGE in $DH_DOPACKAGES; do TMP=`tmpdir $PACKAGE` compress=`pkgfile $PACKAGE compress` @@ -15,26 +41,18 @@ for PACKAGE in $DH_DOPACKAGES; do olddir=`pwd` doit "cd $TMP" - if [ "$compress" ]; then - # The config file is a sh script that outputs the files to be compressed - # (typically using find). - files=`sh $olddir/$compress 2>/dev/null ; true` + # Get the list of files to compress. + if [ "$DH_EXCLUDE_GREP" ]; then + files=`filelist_excluded` else - # By default fall back on what the policy manual says to compress. - files=` - find usr/info usr/man usr/X11*/man -type f ! -name "*.gz" 2>/dev/null ; - find usr/doc -type f \( -size +4k -or -name "changelog*" \) \ - ! -name "*.htm*" ! -name "*.gif" ! -name "*.gz" \ - ! -name "copyright" 2>/dev/null ; - true - ` + files=`filelist` fi if [ "$files" ]; then # This is just a cosmetic fix. - files=`echo $files | tr "\n" " "` + files=`echo $files | tr "\n" " "` - doit "gzip -9 $files" || true + doit "gzip -f9 $files" || true fi # Change back to old pwd. diff --git a/dh_compress.1 b/dh_compress.1 index dbb33e6d..4f2d2d0a 100644 --- a/dh_compress.1 +++ b/dh_compress.1 @@ -3,7 +3,7 @@ dh_compress \- compress files and fix symlinks in package build directories .SH SYNOPSIS .B dh_compress -.I "[-v] [-a] [-i] [--no-act] [-ppackage] [-Ptmpdir]" +.I "[-v] [-a] [-i] [-X] [--no-act] [-ppackage] [-Ptmpdir]" .SH "DESCRIPTION" dh_compress is a debhelper program that is responsible for compressing the files in package build directories, and makes sure that any symlinks @@ -49,6 +49,13 @@ Compress files for the package named "package". .TP .B \-Ptmpdir, \--tmpdir=tmpdir Use "tmpdir" for package build directory. +.TP +.B \-X=item, \--exclude=item +Exclude files that contain "item" anywhere in their filename from being +compressed. For example, -X=.jpeg will exclude jpeg's from compression. +You may use this option multiple times to build up a list of things to +exclude. You can accomplish the same thing by using a debian/compress file, +but this is easier. .SH NOTES The .B \-a diff --git a/dh_debstd b/dh_debstd new file mode 100755 index 00000000..34ea0d46 --- /dev/null +++ b/dh_debstd @@ -0,0 +1,218 @@ +#!/bin/sh -e +# +# Script to be called from debian/rules to setup all the debian specifc +# required files +# Christoph Lameter, <clameter@debian.org> October 10, 1996 +# +# All the parameters are documentation files to be installed. +# (but doc files can also be listed in debian/docs) +# +# This has been gutted and extensively rewritten to function as a debhelper +# command by Joey Hess. + +# Pre-parse command line before we load dh_lib, becuase we use a +# different style of arguments. +for i;do + case "$i" in + -p) PERMS=1 + ;; + -u) UNDOC=1 + ;; + -s) SUMS=1 + ;; + -m) NOAUTOMAN=1 + ;; + -c) NOCOMPRESS=1 + ;; + *) collect="$collect$i " + ;; + esac +done +set -- $collect + +PATH=debian:$PATH:/usr/lib/debhelper +. dh_lib + +# Tolerate old style debstd invocations +if [ "$DH_FIRSTPACKAGE" = "$1" ]; then + shift +fi + +# Subroutines + +# debinit handles the installation of an init.d script +# Parameters: +# $1= name in /etc/init.d +# $2 = scriptname +# $3 = package name +# $4 = extra params for debhelper +debinit() { + PPACKAGE=$3 + SCRIPT=$1 + + INITPARAMS=`grep "^FLAGS=" $2` || true + if [ "$INITPARAMS" != "" ]; then + INITPARAMS=`expr "$INITPARAMS" : 'FLAGS="\(.*\)"'` || true + if [ "$INITPARAMS" ]; then + INITPARAMS="--update-rcd-params='$INITPARAMS'" + fi + fi + + if grep -q NO_RESTART_ON_UPGRADE $2; then + doit "dh_installinit --no-restart-on-upgrade -p$PPACKAGE $INITPARAMS --init-script=$SCRIPT $4" + else + doit "dh_installinit -p$PPACKAGE $INITPARAMS --init-script=$SCRIPT $4" + fi +} + +# Package specific things +# +# The first parameter is the package name +# The second parameter is the directory name of the temp directory +# The third parameter is the prefix for all configuration files to be processed +package() +{ + local i + local X Y + CPACKAGE=$1 + CTEMP=$2 + + # Deal with scripts in etc directories + if [ -f $3/rc.boot ]; then + warning "file $3/rc.boot was ignored." + fi + + # etc files that could need some tweaking + for i in services inittab crontab protocols profile shells rpc shells \ + syslog.conf conf.modules modules aliases diversions inetd.conf \ + X11/Xresources X11/config X11/window-managers X11/xinit purge ; do + if [ -f $3$i ]; then + warning "file $3$i was ignored." + fi + done + + if [ -f $3init.d ]; then + debinit $1 $3init.d $1 "" + fi + + # The case of a daemon without the final d + if [ -f $3init ]; then + X=`expr $1 : '\(.*\)d$'` || true + if [ "$X" ]; then + debinit $X $3init $1 "--remove-d" + fi + fi + + if [ -f $3info ]; then + warning "debhelper does not yet support info files, so $3info was ignored." + fi + + X=`find $2 -type f -perm +111 2>/dev/null | tr "\n" " "` + for i in $X; do + BINPATH="`expr "$i" : "$2/\(.*\)/.*"`" + BINNAME="`expr "$i" : "$2/.*/\(.*\)"`" + + # Check if manpages exist + case "$BINPATH" in + DEBIAN|etc/rc.boot|usr/lib/cgi-bin|etc/init.d|etc/cron.*|usr/lib/lib*|usr/lib/*) SECTION="" + ;; + sbin|usr/sbin) SECTION="8" + ;; + usr/X11R6/bin) SECTION="1x" + ;; + bin|usr/bin) SECTION="1" + ;; + usr/games) SECTION="6" + ;; + *) SECTION="" + ;; + esac + if [ "$SECTION" ]; then + Y=`find $2/usr/man $2/usr/X11R6/man -name "$BINNAME.*" 2>/dev/null` || true + if [ "$Y" = "" ]; then + if [ "$UNDOC" ]; then + doit "dh_undocumented -p$CPACKAGE $BINNAME.$SECTION" + fi + fi + fi + done +} + +packages() { + local i + BASE=$1 + shift + for i in $*; do + package $i debian/$i "debian/$i." + if [ -x debian/$i.prebuild ]; then + warning "file debian/$i.prebuild ignored" + fi + done + + if [ -f debian/clean ]; then + warning "file debian/clean ignored" + fi + package $BASE debian/tmp "debian/" +} + +# Special case of changelog +if [ "$1" ]; then + if echo "$1" | egrep -qi "change|news|history" ; then + changelogfile=$1 + shift + fi +fi + +doit "dh_installdirs" # here just to make the debian/tmp, etc directories. +doit "dh_installdocs $*" +doit "dh_installexamples" +doit "dh_installchangelogs $changelogfile" +doit "dh_installmenu" +doit "dh_installcron" + +# Manpage scan +if [ "$NOAUTOMAN" = "" ]; then + doit "dh_installmanpages -p$DH_FIRSTPACKAGE" +fi + +packages $DH_DOPACKAGES + +doit "dh_movefiles" +doit "dh_strip" + +if [ ! "$nocompress" ]; then + doit "dh_compress" +fi + +doit "dh_fixperms" +doit "dh_suidregister" +doit "dh_shlibdeps" +doit "dh_gencontrol" +doit "dh_makeshlibs" + +# Check to see if the install scripts have #DEBHELPER# in them, if not, +# warn. +for PACKAGE in $DH_DOPACKAGES; do + for file in postinst postrm preinst prerm; do + f="`pkgfile $PACKAGE $file`" + if [ "$f" ]; then + filelist="$filelist$f " + fi + done +done +if [ "$filelist" ]; then + warning "The following scripts do not contain \"#DEBHELPER#\" in them," + warning "and so debhelper will not automatically add commands to them:" + warning "$filelist" +fi + +doit "dh_installdeb" + +if [ "$SUMS" = "" ]; then + doit "dh_md5sums" +fi + +# This causes the main binary package to be built, which +# real debstd does not do. Shouldn't be a problem though, +# if that package gets built twice. +doit "dh_builddeb" diff --git a/dh_debstd.1 b/dh_debstd.1 new file mode 100644 index 00000000..e3568eb6 --- /dev/null +++ b/dh_debstd.1 @@ -0,0 +1,72 @@ +.TH DH_DEBSTD 1 +.SH NAME +dh_debstd \- mimic debstd with debhelper commands +.SH SYNOPSIS +.B dh_debstd +.I "[-v] [--no-act] [-m] [-c] [-u] [-s] [[changelog] file ...]" +.SH "DESCRIPTION" +dh_debstd is a debhelper command that mimics the behavior of debstd, by +calling other debhelper commands. Its behavior is not a complete nor an +exact copy of what debstd does, but it should be close enough to be usable. +.P +dh_debstd is not intended to really be used in building an official debian +package. Instead, it is intended to help you convert your package that uses +debstd over to debhelper. If you run dh_debstd with the same parameters you +passed to debstd, and use the --verbose and --no-act flags, you can see what +debhelper commands dh_debstd runs, and copy those commands into debian/rules +to get a start on converting to debhelper. +.P +See +.BR debstd (1) +for a complete description of what this program does. +.SH "DEBHELPER STYLE OPTIONS" +.TP +.B \-v, \--verbose +Verbose mode; show all commands that modify the package build directory. +.TP +.B \--no-act +Do not really do anything. If used with -v, the result is that this command +will output a list of what it would have done. +.SH "DEBSTD STYLE OPTIONS" +.TP +.B \-m +Switch off automatic man page installation. +.TP +.B \-c +Switch off automatic file compression. +.TP +.B \-u +Enable generation of symlinks to undocumented(7) man page. +.TP +.B \-s +Switch off md5sum file generation. +.TP +.B changelog +Install this file as the upstream changelog. Only happens if it's name +contains "change", "news", or "history" (not case sensative). +.TP +.B file ... +Install these files as documentation. +.SH NOTES +Unlike debstd, dh_debstd does not automatically modify maintainer scripts +such as the postinst, posrm, etc. To get those scripts to be modified, you +have to place "#DEBHELPER#" in them at the location you want debhelper to +insert commands. To help you remember to do that, a warning message will be +generated if dh_debstd notices scripts without "#DEBHELPER#" in them. +.SH ENVIRONMENT +.TP +.I DH_VERBOSE +Enables verbose mode +.TP +.I DH_NO_ACT +Enables no-act mode (see above). +.SH "SEE ALSO" +.BR /usr/doc/debhelper/from-debstd +, +.BR debstd (1) +.SH BUGS +It doesn't completly mimic debstd. Some things debstd handles are not supported +by debhelper. With the exception of buildinfo.Debian files, everything that +is not supported will generate a warning message. +.SH AUTHOR +Joey Hess <joeyh@master.debian.org> diff --git a/dh_getopt.pl b/dh_getopt.pl index 0c9bba0b..b5cde776 100755 --- a/dh_getopt.pl +++ b/dh_getopt.pl @@ -58,6 +58,11 @@ sub AddPackage { my($option,$value)=@_; } } +# Add another item to the exclude list. +sub AddExclude { my($option,$value)=@_; + push @exclude,$value; +} + use Getopt::Long; # Enable bundling of short command line options. @@ -82,7 +87,10 @@ $ret=GetOptions( "x" => \$include, # is -x for some unknown historical reason.. "include-conffiles" => \$include, - + + "X=s" => \&AddExclude, + "exclude=s" => \&AddExclude, + "d" => \$d_flag, "remove-d" => \$d_flag, @@ -134,6 +142,9 @@ if ($ENV{DH_NO_ACT} ne undef) { $no_act=1; } +$exclude=join ' ', @exclude; +$exclude_grep=join '|', @exclude; + # Now output everything, in a format suitable for a shell to eval it. # Note the last line sets $@ in the shell to whatever arguements remain. print qq{ @@ -143,7 +154,9 @@ DH_DOPACKAGES='@packages' DH_DOINDEP='$indep' DH_DOARCH='$arch' DH_NOSCRIPTS='$noscripts' -DH_EXCLUDE='$include' +DH_INCLUDE_CONFFILES='$include' +DH_EXCLUDE='$exclude' +DH_EXCLUDE_GREP='$exclude_grep' DH_D_FLAG='$d_flag' DH_R_FLAG='$r_flag' DH_K_FLAG='$k_flag' @@ -15,7 +15,7 @@ for PACKAGE in $DH_DOPACKAGES; do complex_doit "find $TMP/* -type f ! -regex '^$TMP/DEBIAN/.*' | sed s:$TMP:: | sort > $TMP/DEBIAN/allfiles" # Check if we should exclude conffiles. - if [ ! "$DH_EXCLUDE" -a -r $TMP/DEBIAN/conffiles ]; then + if [ ! "$DH_INCLUDE" -a -r $TMP/DEBIAN/conffiles ]; then complex_doit "sort $TMP/DEBIAN/conffiles | comm -13 - $TMP/DEBIAN/allfiles > $TMP/DEBIAN/allfiles.new" doit "mv $TMP/DEBIAN/allfiles.new $TMP/DEBIAN/allfiles" fi diff --git a/doc/PROGRAMMING b/doc/PROGRAMMING new file mode 100644 index 00000000..7dc0c638 --- /dev/null +++ b/doc/PROGRAMMING @@ -0,0 +1,187 @@ +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: +------------------ + +All debhelper programs use the dh_lib library (actually it's a shell script) +to parse their arguments and set some useful variables. It's not mandatory +that your program use dh_lib, 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. + +Typically, you invoke dh_lib like this: + +PATH=debian:$PATH:/usr/lib/debhelper +. dh_lib + +The path statement is there to make your program look first in debian/ for +dh_lib (so users can install a modified version there if necessary), then the +rest of the path, then the canonical location of dh_lib, /usr/lib/debhelper. + +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 handles argument +processing. + +As soon as dh_lib loads, it processes any arguments that have been passed to +your program. The following variables may be set during this stage; your +program can use them later: + +switch variable description +-v DH_VERBOSE should the program verbosely output what it is + doing? +--no-act DH_NO_ACT should the program not actually do anything? +-i,-a,-p DH_DOPACKAGES a space delimited list of the binary packages + to act on +-i,-p DH_DOINDEP a space delimited list of the binary independent + packages to act on +-a,-p DH_DOARCH a space delimited list of the binary dependent + packages to act on +-n DH_NOSCRIPTS if set, do not make any modifications to the + package's postinst, postrm, etc scripts. +-X DH_EXCLUDE exclude a something from processing (you + decide what this means for your program) + DH_EXCLUDE_GREP same as DH_EXCLUDE, except all items are + separated by '|' characters, instead of spaces, + handy for egrep -v +-x DH_INCLUDE_CONFFILES + include conffiles. It's -x for obscure + historical reasons. +-d DH_D_FLAG you decide what this means to your program +-r DH_R_FLAG you decide what this means to your program +-k DH_K_FLAG you decide what this means to your program +-P DH_TMPDIR package build directory (implies only one + package is being acted on) +-u DH_U_PARAMS will be set to a string, that is typically + parameters your program passes on to some + other program. +-m DH_M_PARAMS will be set to a string, you decide what it + means to your program +-V DH_V_FLAG will be set to a string, you decide what it + means to your program +-V DH_V_FLAG_SET will be 1 if -V was specified, even if no + parameters were passed along with the -V +-A DH_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 DH_INIT_SCRIPT will be set to a string, which specifies an + init script name (probably only + dh_installinit will ever use this) + +Any additional command line parameters that do not start with "-" will be +ignored, and you can access them later just as you normally would ($1, $2, +etc). + +If you need a new command line option, just ask me, and I will add it. + +Global variables: +---------------- + +The following variables are also set, you can use any of them: + +MAINPACKAGE the name of the first binary package listed in + debian/control +DH_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 also contains a number of functions you may find useful. + +doit() + Pass this function a string 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() + This is the same as doit(), except you can pass more complicated + commands to it (ie, commands involving piping redirection) +verbose_echo() + 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". +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 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 + 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, VERSION is set to the version number of the + package. +autoscript() + Pass 3 parameters: + 1: script to add to + 2: filename of snippet + 3: 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). + +Notes: +----- + +Dh_lib is still evolving. +There will probably be a perl version too, in the future. + +-- Joey Hess <joeyh@master.debian.org> diff --git a/doc/README b/doc/README new file mode 100644 index 00000000..986eb02c --- /dev/null +++ b/doc/README @@ -0,0 +1,100 @@ +Debhelper is a collection of programs that can be used in debian/rules files +to automate common tasks. For further documentation, see the man pages for +dh_* commands. + +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). + +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 new 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: + +print << `EOF` +#DEBHELPER# +EOF + + +Notes on multiple binary packages: +--------------------------------- + +If your source package generates more than one binary package, debhelper +programs will default to acting on all binary packages when run. If your +source package happens to generate one architecture dependent package, and +another architecture independent package, this is not the correct behavior, +because you need to generate the architecture dependent packages in the +binary-arch debian/rules target, and the architecture independent packages +in the binary-indep debian/rules target. + +To facilitate this, as well as give you more control over which packages +are acted on by debhelper programs, all debhelper programs accept the +following parameters: + +-a Act on architecture dependent packages +-i Act on architecture independent packages +-ppackage Act on the package named "package" (may be repeated multiple + times) + +These parameters are cumulative. If none are given, the tools default to +affecting all packages. + +See examples/rules.multi for an example of how to use this. + +Package build directories -- debian/tmp, etc: +-------------------------------------------- + +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. + +Sometimes, you might want to use some other temporary directory. This is +supported by the -P flag. The directory to use is specified after -P, for +example, "dh_installdocs -Pdebian/tmp", will use debian/tmp as the temporary +directory. Note that if you use -P, the debhelper programs can only be +acting on a single package at a time. So if you have a package that builds +many binary packages, you will need to use the -p flag to specify which +binary package the debhelper program will act on. For example: + + dh_installdocs -pfoolib1 -Pdebian/tmp-foolib1 + dh_installdocs -pfoolib1-dev -Pdebian/tmp-foolib1-dev + dh_installdocs -pfoolib-bin -Pdebian/tmp-foolib-bin + +This uses debian/tmp-<package> as the package build directory. + +Other notes: +----------- + +* 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/tmp/DEBIAN/ + before trying to put files there, dh_installmenu knows you need a + debian/tmp/usr/lib/menu/ before installing the menu files, etc. + +-- Joey Hess <joeyh@master.debian.org> diff --git a/doc/TODO b/doc/TODO new file mode 100644 index 00000000..188e3c6c --- /dev/null +++ b/doc/TODO @@ -0,0 +1,26 @@ +* add all other functionality of debstd (??) + - add a program to generate file similar to buildinfo.Debian generated by + debmake (wishlist bug #17043). I just never saw the point of that file.. + - Make dh_movefiles remove emptied directories after it's moved all the + files out of them (wishlist bug #17111). +* 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 fragements wouldn't go into the postinst. So maybe a + new script is called for. +* info support for debhelper (currently implemented, but I hate how I did it, + so it's not in the package.) (wishlist bug #15717) +* 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. +* 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. diff --git a/doc/from-debstd b/doc/from-debstd new file mode 100644 index 00000000..31fd0cdd --- /dev/null +++ b/doc/from-debstd @@ -0,0 +1,63 @@ +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 --act" +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-gencontol 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> @@ -0,0 +1,2 @@ +x="debian|autoscripts" +find |grep -F "`echo "$x" | tr "|" "\n"`"
\ No newline at end of file diff --git a/from-debstd b/from-debstd new file mode 100644 index 00000000..31fd0cdd --- /dev/null +++ b/from-debstd @@ -0,0 +1,63 @@ +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 --act" +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-gencontol 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> |