Creating a Debian / Ubuntu package for a PHP PECL extension

Aug 11 2012

Today I wanted to use the Inotify functions that are supplied by the PECL Package Inotify. It turns out that this PHP extension is not available in the (default) Debian or Ubuntu repositories. Instead of using the PECL command to install the extension, I wanted to create a native package that I could use to install/uninstall the package on multiple servers. This blogpost describes how I did this:

1. Downloading and unpacking the extension

Note that I will create a package for the Inotify extension in this blogpost, but this guide can be applied to any PHP (PECL) extension.

  • Create a working directory:
    mkdir php-notify
    cd php-notify
  • Download the extension:
    wget ''
  • Unpack the extension:
    tar -zxvf inotify-0.1.6.tgz
  • The current directory should now contain the extension archive (inotify-0.1.6.tgz) a package.xml file and a directory containing the source of the extension (i.e. inotify-0.1.6). You can verify this with:
    ls -las

2. Preparing the extension for packaging

The source code should be in place. Now it's time to prepare the extension for packaging.

  • Make sure you have the needed tools installed to build the extension:
    sudo aptitude update
    sudo aptitude install build-essential checkinstall
  • Change directory to the extension source directory:
    cd inotify-0.1.6
  • Run phpize to prepare the build environment for the extension:
  • Configure, compile and test the extension:
    make test

These steps are also documented in the PHP manual at Compiling shared PECL extensions with phpize.

3. Creating a package

Now that we have compiled the extension, lets create a package for it! Creating a package is really easy now, all you have to do is issue the checkinstall command, the --install=no parameter prevents the package from being installed immediately. You should run this command as root, because otherwise files could end up having the wrong permissions.

sudo checkinstall --install=no

You can answer with "y" to the question about the ./doc-pak directory that does not exist. After that you can input a description for your extension. Then you're given an overview of the package to be build, you can change any of the properties. Change at least the name of the package, I changed it to "php5-inotify-custom". Hit ENTER to build the package now.

The name of the created package is printed by the checkinstall script (php5-inotify-custom_0.1.6-1_amd64.deb in my case). Now you can install the package with dpkg:

sudo dpkg -i php5-inotify-custom_0.1.6-1_amd64.deb

After installation you can enable the module by creating a new file "/etc/php5/conf.d/inotify.ini" containing the text "" (make sure to restart your webserver if needed). If you don't want to create this file manually after installation of the package, read the next chapter.

sudo echo '' > /etc/php5/conf.d/inotify.ini
sudo service apache2 reload

The package can be uninstalled with dpkg too:

sudo dpkg -P php5-inotify-custom

4. Creating a package that enables the extension

I wanted to create a package that would enable the the new module straight away. This is how I did this:

  • I created a config file for inotify.ini in the /etc/php5/conf.d directory. This directory is automatically scanned for (additional) configuration files for PHP in Debian and Ubuntu:
    sudo echo '' > /etc/php5/conf.d/inotify.ini
  • To include this file in the package, we must create a text file containing the path to this file:
    echo '/etc/php5/conf.d/inotify.ini' > checkinstall_files.txt
  • Now run checkinstall like this and follow the steps that are outlined in the previous chapter:
    sudo checkinstall --install=no --include=checkinstall_files.txt
    sudo rm /etc/php5/conf.d/inotify.ini
    You can skip the last step to enable the module.

If you run into errors or warnings when installing this package via dpkg, you should read Checkinstall configfiles bug at the bottom of this post.

Why did I build a package?

So why did I build a package instead of installing the extension with the PECL command? I did this because there are quite a few advantages in creating a (custom) package:

  • It can be installed and uninstalled via the system's own package manager (dpkg).
  • When you're running your own package repository it's really easy to install the package on multiple servers (via apt-get/aptitude).
  • When you're using a tool such as Puppet to manage your servers you can add this to the list of packages that must be installed.
  • The system is aware that the package is installed and which version of the package is installed. You can also define the package dependencies for your custom packages.

Checkinstall configfiles bug

After adding the config file (/etc/php5/conf.d/inotify.ini) to the list of files that should be included in the package I started getting warnings when installing (and removing) the package. After some searching, I found a blog entry called Bug in checkinstall regarding conffiles, that explains the warnings and provides a solution for this problem.