Creating Gnope PEAR packages


Table of Contents

About the tutorial
Creating a package.xml file
Gnope package specialities
Using special directories
Creating the package
Testing the package
Publishing
A. Links
B. Credits

About the tutorial

This tutorial describes how to pack your applications into PEAR compatible packages and publish them on the gnope.org PEAR channel.

Having your application packed in a PEAR compatible package has several advantages:

  • Your program is installable very easily via the PEAR_Frontend software installer delivered with Gnope, or via command line.

  • The program can be updated easily

  • You can have dependencies to other PHP libraries and programs that can be installed and upgraded automatically

  • You have just one single file to distribute

  • Installation is a breeze

The applications on the Gnope channel server are just PEAR packages, with the difference that the Gnope team decides which programs are listed.

Creating a package.xml file

The base for a package is an xml file called package.xml. You can create it either by hand, or use a graphical tool that creates one for you. The graphical tools are under development and should reach PEAR in some weeks.

Creating the package from scratch isn't very easy; it's probably the best to take the package.xml from an existing package and modify it to suit your needs and your applicaton.

If you plan to publish the package on the Gnope channel, you need to set the lead maintainer name to your nickname of the Gnope forums.

Gnope package specialities

Gnope packages are normal PEAR packages with some extensions:

  • If the packages contain a "run.phpw" file, they are shown in the AppRunner tool and can be executed from there without using the command line. The file should just include the main class and start the application. Give the run.phpw file a "doc" role if you want to be 100% correct.

  • You can give your application an icon in AppRunner by providing a "runicon.png" file in the same directory as the run.phpw one.

Using special directories

Files in package.xml get a "role". Standard one is "php", but you can also use "data" and several others. The "php" role is meant to be used with .php files, while "data" is for not code-related files like images or configuration files. In your code, you need to use the path of the data dir when loading this files.

To get a file from the data dir, you can do the following:

require_once "PEAR/Config.php";
$configfile = PEAR_Config::singleton()->get('data_dir') . DIRECTORY_SEPARATOR . get_class($this) '.ini';
$graphic = PEAR_Config::singleton()->get('data_dir') . DIRECTORY_SEPARATOR . 'MyPackage/graphic.png';

The variable $configfile contains the path to the config file with the name of the current class, while $graphic contains the full path of a graphic installed in the data dir of the MyPacakge package.

Creating the package

You don't need to use a zip program or so; the PEAR command line tool provides the functionality and makes creating packages really easy: Open a shell, navigate to the directory that contains the package.xml file and type

pear package

That will cause PEAR to read the package.xml file, verify it and create the .tgz package file that you can distribute. If there are errors in it, the building proces will fail and an error message will be shown, telling you what to fix.

Testing the package

It is very, very important to test the package before distributing it to the users. There are several things that can fail:

  • Not all files are included in the package, because you didn't update the package.xml file

  • Files are installed into a different directory structure than you used in the build

  • Files with another role than "php" (e.g. data) wll be installed in a totally different directory, but your code assumes them in the same location as the php files

  • ...

Installing the package is very easy, just type

pear install MyPackage-0.0.1.tgz

The PEAR installer will take the local file and try to install it. If you already have a previous version of your application installed, use the upgrade command:

pear upgrade MyPackage-0.0.1.tgz

If you fixed something in your package.xml and created a new file with the same version as currently installed, pear upgrade will fail. Use the -f parameter to force the installation:

pear upgrade -f MyPackage-0.0.1.tgz

Now test if the installed application works: Switch into a different directory (very important not to use the development directory!) and use

php /path/to/pear/my/application/run.phpw

to run it. Here is the place at which you see what the users will see, and have the chance to find and fix errors.

Publishing

If your package has been tested and works well, you might want to publish it to let a broad audience use and test it.

You can either use the Gnope PEAR channel to distribute it, or set up your own channel server.

To publish the application on Gnope, go to and upload your file. Someone of the Gnope team will review and test it a bit, and make it public on the channel. You will get a channel account with the same nickname and password as in the Gnope forum.

A. Links

B. Credits

The document has been written by Christian Weiske, cweiske@cweiske.de on 2006-04-04. Critics, thanks and ideas are always welcome.

This document is licensed under a Creative Commons license.