1. Policy for PEAR modules

1.1 Package name

the PEAR package name should :

1.2 What the package has to achieve

PEAR has its own packaging system, and debian packages have to register themselves with PEAR.

You may use pear install -r package.xml in postinst and pear uninstall -r PEAR_MODULE_NAME in prerm to achieve that

1.3 Other Packaging Notes

1.4 Other Advices

Respond to bugs, use rss2email to subscribe to the RSS feed for that package to know about new releases.

2. A packaging suggestion

We wanted to fulfill a few wishes :

2.1 Create the debian/ dir

First, get the official pear module you want to package using the pear command from the php4-pear package

~$ pear download MDB
File MDB-1.3.0.tgz downloaded (218957 bytes)

And then prepare our deb-source tree : rename the tgz into a package_version.orig.tar.gz, and unpack it.

~$ mv MDB-1.3.0.tgz php-mdb_1.3.0.orig.tar.gz
~$ mkdir php-mdb
~$ cd php-mdb
~/php-mdb$ tar xzf ../php-mdb_1.3.0.orig.tar.gz
~/php-mdb$ mkdir debian
~/php-mdb$ echo 4 > debian/compat
~/php-mdb$ ls
MDB-1.3.0 debian package.xml

I know that to decompress the orig.tar.gz into a subdir seems to be awkward, but in fact, it has a file (package.xml) that is at the toplevel of the archive, and dpkg knows how to deal with it alone ! big good boy ;)

2.2 Create the debian/rules script

how it works ? In three steps :

  1. It creates some scripts and files from templates (postinst, prerm, watch)
  2. It creates the PEAR tgz again (see in build: target)
  3. And then use pear to install it in the debian/foo/ subtree

The very good points here are :

The bad point is that pear does at the same time : configure, make and make install. So it's hard to split them (build: and binary: targets of the debian/rules)

You only need to copy the following debian/rules :

you have to get the pear.xsl used to generate the upstream's changelog

#!/usr/bin/make -f

pear_pkg := $(shell xpath -q -e '/package/name/text()' package.xml)
package = $(shell echo php-$(pear_pkg) | tr '[:upper:]_' '[:lower:]-')

clean:
        rm -f \
                debian/package.tgz \
                debian/$(package).postinst \
                debian/$(package).prerm \
                debian/watch \
                debian/Changelog
        dh_testdir
        dh_testroot
        dh_clean

build:
        cat debian/postinst.tpl | perl -e 'while(<>) { exit if /@xml@/; print;}' \
                        >  debian/$(package).postinst
        cat package.xml >> debian/$(package).postinst
        cat debian/postinst.tpl | perl -e 'while(<>) { print if $$b; $$b=1 if /@xml@/;}' \
                        >> debian/$(package).postinst

        cat debian/prerm.tpl | sed -e 's/@pear_pkg@/$(pear_pkg)/g' \
                        > debian/$(package).prerm

        cat debian/watch.tpl | sed -e 's/@pear_pkg@/$(pear_pkg)/g' \
                        > debian/watch

        xsltproc --nonet --novalid debian/pear.xsl package.xml > debian/Changelog

        tar czf debian/package.tgz `ls | grep -v debian`

binary: binary-arch binary-indep
        # Nothing to do here

binary-arch:
        # Nothing to do here

binary-indep:
        dh_testdir
        dh_installdirs

        # Custom package commands
        pear install -n -R debian/$(package)/ debian/package.tgz
        rm -rf \
                debian/$(package)/usr/share/php/.filemap \
                debian/$(package)/usr/share/php/.lock \
                debian/$(package)/usr/share/php/.registry

        # Resume debhelper scripts
        dh_testroot
        dh_installchangelogs  debian/Changelog
        dh_installdocs
        dh_installdeb
        dh_fixperms
        dh_compress
        dh_gencontrol
        dh_md5sums
        dh_builddeb

.PHONY: binary binary-arch binary-indep build clean

2.3 create the postinst template

We need to keep the package.xml safe, since it allows us to register the package in PEAR.

You'll have to create a debian/postinst.tpl which should have a line beeing exactly '@xml@', that will be replaced by the package.xml content. It should looks like :

#! /bin/sh

set -e

case "$1" in

    configure)
        curdir=`pwd`
        tmp=`mktemp -t -d`
        cd $tmp
        (cat <<-EOF
@xml@
EOF
        ) > package.xml
        pear install -r package.xml &>/dev/null
        cd $curdir
        rm -rf $tmp
    ;;

    abort-upgrade|abort-remove|abort-deconfigure)
    ;;

    *)
        echo "postinst called with unknown argument \`$1'" >&2
        exit 1
    ;;

esac

#DEBHELPER#

exit 0

2.4 Create the prerm template

We have to know the PEAR's module name here, in order to be unregistered from PEAR at remove, upgrade or deconfigure time. You have to create a prerm.tpl containing the @pear_pkg@ token, that will be replaced by the PEAR's module name :

#!/bin/sh

set -e

case "$1" in
    remove|upgrade|deconfigure)
        pear uninstall -r @pear_pkg@ 1>/dev/null 2>/dev/null
    ;;

    *)
    ;;
esac

#DEBHELPER#

exit 0

2.5 Create the watch template

It works like the postrm template does. it replaces the @pear_pkg@ token with the PEAR's module name. So here is a watch.tpl example: 

version=2
http://pear.php.net/package/@pear_pkg@/download /get/@pear_pkg@-([\d.]+)\.tgz

2.6 further notes

don't forget to create debian/changelog, debian/copyright (see policy above) and debian/control file, and you'll be done

be carefull, your Build-Depends(-Indep) in debian/control has to mention php4-pear, libxml-xpath-perl and xsltproc

TODO: