Differences between revisions 29 and 30
Revision 29 as of 2013-03-16 11:44:44
Size: 9292
Comment:
Revision 30 as of 2015-01-10 18:27:40
Size: 9275
Editor: GuillemJover
Comment: Use dpkg-parsechangelog option instead of sed/grep+cut
Deletions are marked like this. Additions are marked like this.
Line 140: Line 140:
DEB_VERSION := $(shell dpkg-parsechangelog | egrep '^Version:' | cut -f 2 -d ' ') DEB_VERSION := $(shell dpkg-parsechangelog --show-field=Version)

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

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 section:

  • should be php

Package name:

  • should be prefixed with php-

  • should be lowercased
  • should have all underscores be replaced by dashes

Package short description:

  • may begin with PHP Pear module(s) for ...

  • may be inspired from <summary> in package.xml

Package description:

  • may be inspired from <description> in package.xml

Depends:

  • should have php-pear, probably versionned (See <dependencies> in package.xml)

  • should be inspired from <dependencies> in package.xml

Maintainer field:

Uploaders field:

  • should be set to main maintainer in first (if you are here, you are the first responsible of this package)
  • may eventually list co-maintainers

Other fields follow current best practice (Homepage, Vcs-*, ...)

Example :

Source: php-foo-bar
Section: php
Priority: extra
Maintainer: Debian PHP PEAR Maintainers <pkg-php-pear@lists.alioth.debian.org>
Uploaders: Foo packager <foobar@example.org>
Build-Depends: debhelper (>= 7), dh-make-php, cdbs
Standards-Version: 3.9.1
Homepage: http://pear.php.net/package/Foo_Bar/
Vcs-Svn: svn://svn.debian.org/pkg-php/pear/php-foo-bar/trunk
Vcs-Browser: http://svn.debian.org/wsvn/pkg-php/pear/php-foo-bar/trunk

Package: php-foo-bar
Architecture: all
Depends: ${misc:Depends}, php-pear
Description: PHP Pear module(s) for Foo_Bar
 This PHP module has foo and bar included.

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:

  1. no register
  2. register in postint and unregister in prerm

  3. 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).

By default, dh-make-pear use CDBS.

If you can use debhelper version 8 and later, use pkg-php-tools, which ships a dhpear tool that does all the above and variable substitution in debian/control. See also http://php.debian.net/.

If you want debhelper before version 8, here is example for debian/rules file:

 #!/usr/bin/make -f

DEB_VERSION := $(shell dpkg-parsechangelog --show-field=Version)
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_prep
    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-dependent files here.
binary-arch: build install
# We have nothing to do by default.

# Build architecture-independent files here.
binary-indep: 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-pear (http://lists.alioth.debian.org/mailman/listinfo/pkg-php-pear) ). You should also consider to join pkg-php alioth team (http://alioth.debian.org/projects/pkg-php) and commit your package(s) in the Git repository (see PHP/GitUsage, or SVN repository, now slightly deprecated).

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-pear@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.