php5 - Packaging fpm for ubuntu 9.10

This guide intended to outline how to re-package the php5 distribution, with php-fpm. What is php-fpm and why would you want to re-package php5 with it? I hear you say. Php-fpm is like a baked-in version of fast cgi for php, and currently the most efficient, speedy way of serving up .php pages. It's even better than light-httpd's spawn-fcgi. Here's a comparison chart where the relative merits of fpm are highlighted. This will make an excellent choice when combined with a fast new-breed web server such as nginx.

So down to business. We will compile php without the apache webserver and with the fpm patch for php. We don't want apache as we'll be using nginx to help take advantage of our new-found performance gains. A closer look at the ubuntu package repository shows us that there are many variants of php5 available on ubuntu. All variants are built / derived from one large source package, which contains all of the build options, files, patches, etc for all such variants.

Step 0 - Become an ubuntu contributor

The ubuntu GettingStarted playbook.pdf is a good place to start.

And this document will tell you how to make yourself a gpg key (for package signing): The ubuntu GnuPrivacyGuardHowto. Once we have made our gpg key it can be uploaded to the Ubuntu keyserver. Finally you must link your uploaded key to your Launchpad Account, which can be done through the Profile settings page https://launchpad.net/~yourlaunchpadusername/+editpgpkeys.

We'll also need get set up with certain special developer tools like dpkg and quilt. The ubuntu wiki has some more guides and documents to help us.

Step 1 - Download the php5 ubuntu source package

Some informed searching should bring to this page. It points to the links for the source files. At the time of writing the newest package is (5.2.10.dfsg.1-2ubuntu1).

Lets begin by downloading the 3 files of 5.2.10.dfsg.1-2ubuntu1. They are all hosted on launchpad.

sudo chown -R user:grp /usr/local/src # Might need to do this first
cd /usr/local/src
dget -xu https://launchpad.net/ubuntu/karmic/+source/php5/5.2.10.dfsg.1-2ubuntu1/+files/php5_5.2.10.dfsg.1-2ubuntu1.dsc
# dpkg-source -x php5_5.2.10.dfsg.1-2ubuntu1.dsc

The php source tree is dumped into a directory called /usr/local/src/5.2.10.dfsg.1. Our ubuntu package version of the source tree contains all the php5 src files, of course. But there is also a debian/ subfolder. This is where the we will make changes.

Step 2 - Create the php-fpm patch file

Fpm is generally distributed as a patch to the php5 source tree. The fpm sources are also versioned code under vcs. In order to get the latest patch (and that is compatible with the php release), we must download the source tree and bundle it into the debian package.

# Checkout from Github (git)
git clone git://github.com/dreamcat4/php-fpm.git

# Or Launchpad (bzr)
bzr branch lp:~dreamcat4/php-fpm/master

# Generate the patch file
./php-fpm/generate-fpm-patch

The above two lines creates a file named php-fpm.patch in the current directory, one-level-up above the source files. It must be copied to the debian/patches folder. But first we should...

Step 4 - Version our changes

Our main task is editing the build scripts that exist in the debian/ subfolder.

We are using Git version control to keep track of our intermediate steps. Finished changes will be diffe'd out to launchpad when they are done.

Here is the working changeset in Github: php5-5.2.10.dfsg.1.

Step 5 - Add 'php-fpm' build target

These changes are numerous. Patch goes in debian/patches. Description added to: debian/control. Build script: debian/rules. The changes are too numerous to mention individually. See the commit history.

Step 6 - Setup chroot environment

If we with to build for a particular release, our host system must be greater than or equal to that release. Therefore to build for karmic release, we must be on a 9.10 (karmic) system.

sudo pbuilder --create --distribution karmic

Step 7 - Build, and re-build .deb binaries

The source monolithic php5 source package will compile all of the php5 variants in one run. Theres no option to select one or other of the target packages. Be warned - this next command may take (hours) to complete.

pdebuild -- --distribution karmic

The other way to build (not in a chroot environment)

aptitude build-dep php5
dpkg-buildpackage -uc -b

Step 8 - Fine-tune .deb package

Peeking inside the .deb binaries reveals what files would be installed.

# List the files in the .deb binary package
dpkg --contents php5-fpm_5.2.10.dfsg.1-2ubuntu1_i386.deb

It may be necessary go back and iterate over steps 5-6 to fix any missing or misplaced commands. Expect some rather lengthy compilations in between your edits as the php sources are over 90MB uncompressed. Commit the changes to vcs and re-build.

Step 7 - Produce a local binary build

The build steps are as follows:

cp -Rf php5-5.2.10.dfsg.1 php5-5.2.10.dfsg.1-build
cd php5-5.2.10.dfsg.1-build
rm -Rf ./.git* ./*-files.out ./debian/.git*
dpkg-buildpackage

Step 9 - Build source package, Upload to Launchpad

For the source package, we follow these wiki articles for building and uploading

# .dsc uploads should be appended with ~pre1, ~pre2 in the changelog whilst under testing
cp -Rf php5-5.2.10.dfsg.1 php5-5.2.10.dfsg.1~pre1
cd php5-5.2.10.dfsg.1~pre1
rm -Rf ./.git* ./*-files.out ./debian/.git*
debuild -S && echo $? && cd ..
dput dreamcat4-testing  php5_5.2.10.dfsg.1-2ubuntu1~pre1_source.changes

Review process

Patching Guidelines, Sponsorship for existing package, MOTU for a new package

This php package is an existing source so it's covered by ubuntu-main-sponsors group. We subscribe our bug to ubuntu-main-sponsors and also add a needs-verification tag. It should end up on this list.

We then enter a process of more rigourous group-based testing and verification, in which we may be asked to make further modifications. Its not unusual to have several iterations of improvement. The purpose of this final stage to reach a position whereby the package is be deemed safe enough to go upstream.

If successful, the package eventually becomes a release. If not it remains in your PPA (Personal Package Archive).

changed August 24, 2009