Here is a draft of Developer's Reference for packaging PHP PEAR modules. This is inspired by dh-make-php package and Webapps-Pear-Policy-Manual-DRAFT (in webapps SVN repository).
Index ?TableOfContents(2)
Packaging
Hierarchy
Upstream sources are in .tgz and contains package.xml and PEARLIBRARYNAME-x.y.z/ directory. Then, here is aborescence of source package:
$ ls php-PEARLIBRARYNAME-x.y.z-n PEARLIBRARYNAME-x.y.z/ debian/ package.xml
debian/control
Package name should:
- be prefixed with 'php-'
- be lowercased
- have all underscores be replaced by dashes
Package short description should:
- begin with "PHP Pear module(s) for"...
be inspired from <summary> in package.xml
Package description should:
be inspired from <description> in package.xml
mention Homepage: http://pear.php.net/package/PEARLIBRARYNAME
Depends should:
have php-pear, probably versionned (See <dependencies> in package.xml)
Note we have PEAR 1.4.11 in php-pear etch package (version 5.2.0-8*), and if could be a good idea to use (>= 5.2.0-8) if possible to make backport easier.
Maintainer field should:
be set to: Debian PHP Maintainers <pkg-php-maint@lists.alioth.debian.org>
Uploaders field sould:
- be set to main maintainer in first (if you are here, you are the first responsible of this package)
- eventually co-maintainers
(NEW!) Homepage field sould:
be set to: http://pear.php.net/package/PEARLIBRARYNAME
(NEW!) Vcs-* should:
- be set to
Vcs-Svn: svn://svn.debian.org/pkg-php/pear/php-PEARLIBRARYNAME/trunk Vcs-Browser: http://svn.debian.org/wsvn/pkg-php/pear/php-PEARLIBRARYNAME/trunk
Of course, only if you use pkg-php SVN repository, but it's highly recommended.
debian/rules
There are two principal ways for actual pear packages : with cdbs or debhelper.
With CDBS, rules files is trivial (it's the principe ;):
include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/cdbs/1/class/pear.mk
With debhelper, please read /usr/share/cdbs/1/class/pear.mk file, see example below and read sources of existing packages (php-date...)
Note that are three ways to deal with register/unregister modules:
- no register
register in postint and unregister in prerm
- put register files in binary packages
You should avoid to choose first way.
A lot of packages use third way (php-log, php-date, php-soap, php-auth, php-auth-http, php-cache, php-compat, php-config, php-crypt-cbc, php-event-dispatcher, php-file, php-html-common, php-http-request, php-http-upload, php-image-barcode, php-image-canvas, php-image-graph, php-net-checkip, php-net-dime, php-net-ftp, php-net-ipv4, php-net-ldap, php-net-ping, php-net-portscan, php-net-sieve, php-net-smartirc, php-net-url, php-services-weather, php-xml-rss, php-xml-serializer, php-xml-util).
We should probably choose between second and third in order to have uniform packaging. See [discussions on pkg-php alioth list-> http://lists.alioth.debian.org/pipermail/pkg-php-maint/2007-September/003050.html] and note we should have two separated directories (one for debian-packaged modules and other for locally installed), then third is probably recommended..
debian/copyright
PEAR modules could be under various licences : PHP, BSD, LGPL, Apache, MIT, etc. You should verify copyright in all files and write all copyright and authors (with email address).
Note: If your module is under PHP license, it should be version >= 3.01 If it's not, ask to upstream to upgrade to version 3.01 before uploading. BTW you should talk to upstream to convince them to switch to "standard" license like BSD or LGPL.
debian/watch
You should write a watch file looking like:
version=3 http://pear.php.net/package/PEARLIBRARYNAME http://download.pear.php.net/package/PEARLIBRARYNAME-([\d.]+)\.tgz
Concrete example
- Download PEAR module from pear.php.net, for example FOO_Bar
Exec dh-make-pear FOO_Bar-1.2.3.tgz
Correct php-foo-bar-1.2.3/debian/control (Depends:, add "PHP PEAR module for" in short description, add Homepage in long description)
Correct php-foo-bar-1.2.3/debian/copyright
- Verify, build, verify, test (install, remove, etcetera) with classical tools (pbuilder, lintian, linda).
By default, dh-make-pear use CDBS. If you want debhelper, here is example for debian/rules file:
DEB_VERSION := $(shell dpkg-parsechangelog | egrep '^Version:' | cut -f 2 -d ' ') DEB_NOEPOCH_VERSION := $(shell echo $(DEB_VERSION) | cut -d: -f2-) DEB_UPSTREAM_VERSION := $(shell echo $(DEB_NOEPOCH_VERSION) | sed 's/-[^-]*$$//') PEAR ?= /usr/bin/pear pear_pkg = $(shell ls |grep PEARLIBRARYNAME) package = php-auth configure: configure-stamp configure-stamp: dh_testdir touch configure-stamp build: build-stamp build-stamp: configure-stamp dh_testdir touch build-stamp clean: dh_testdir dh_testroot if [ -f $(pear_pkg)/package.xml ]; then \ rm $(pear_pkg)/package.xml; \ fi dh_clean build-stamp configure-stamp install: build dh_testdir dh_testroot dh_clean -k dh_installdirs # Add here commands to install the package into debian/package. cp package.xml $(pear_pkg)/package.xml; $(PEAR) \ -c debian/pearrc \ -d include_path=/usr/share/php \ -d php_bin=/usr/bin/php \ -d bin_dir=/usr/bin \ -d php_dir=/usr/share/php \ -d data_dir=/usr/share/php/data \ -d doc_dir=/usr/share/php/docs \ -d test_dir=/usr/share/php/tests \ install -n -f -P debian/$(package) $(pear_pkg)/package.xml # remove unwanted files rm -f debian/$(package)/usr/share/php/.filemap; rm -f debian/$(package)/usr/share/php/.lock; rm -rf debian/$(package)/usr/share/php/.channels; rm -rf debian/$(package)/usr/share/php/.depdblock; rm -rf debian/$(package)/usr/share/php/.depdb; rm -rf debian/$(package)/usr/share/php/.registry/.channel.pecl.php.net; rm -rf debian/$(package)/usr/share/php/.registry/.channel.__uri; rm -rf debian/$(package)/tmp # remove duplicated files, these files are in /usr/share/doc/package rm -rf debian/$(package)/usr/share/php/tests \ debian/$(package)/usr/share/php/docs # Build architecture-independent files here. binary-indep: build install # We have nothing to do by default. # Build architecture-dependent files here. binary-arch: build install dh_testdir dh_testroot dh_installdocs dh_installexamples dh_installchangelogs dh_compress dh_fixperms dh_installdeb dh_gencontrol dh_md5sums dh_builddeb binary: binary-indep binary-arch .PHONY: build clean binary-indep binary-arch binary install configure get-orig-source: wget http://download.pear.php.net/package/PEARLIBRARYNAME-${DEB_UPSTREAM_VERSION}.tgz \ -O php-PEARLIBRARYNAME_${DEB_UPSTREAM_VERSION}.orig.tar.gz
Collaborative Maintenance
There are more 400 PHP PEAR modules. We don't want have all this packages in Debian, but only packages required for webapps in Debian and maintained/high-quality modules with real use case.
If you are maintainer of PHP PEAR module
Note that your work is not only doing first package. You are Debian Maintainer and you must respond to bugs, follow upstream news (RSS feed, security issues), follow some lists (debian-devel-announce, webapps, pkg-php). You should also consider to join pkg-php alioth team and commit your package(s) in SVN repository.
If you want a new PHP PEAR module
If you want PHP PEAR module because your webapp use it, or because you think there is a use case, ask it by classical debian way : report a RFP (Request For Package) bug against wnpp. Here is an example of email for that:
To: submit@bugs.debian.org Subject: RFP: PEARLIBRARYNAME -- PHP PEAR Module for ... X-Debbugs-CC: pkg-php-maint@lists.alioth.debian.org Package: wnpp Severity: wishlist * Package name : PEARLIBRARYNAME * Version : x.y.z * Upstream Author : Name <somebody@some.org> * URL : http://http://pear.php.net/package/PEARLIBRARYNAME * License : (GPL, LGPL, BSD, MIT/X, etc.) Description : ... -- John Doe
PEAR maintainers from pkg-php team will see if you request is admissible and packaging/uploading/maintaining.