Using Pyrus to create PECL packages

As a PECL developer, managing your extensions could not be simpler with Pyrus. The new pickle command makes creating a package.xml as simple as creating a few text files and then running the command. In addition, the PECL packages created with the pickle command are installable by the most widely installed version of PEAR as well as by the newest versions of PEAR and by Pyrus.

Pyrus's pickle command fully eliminates the need to ever even look at package.xml, greatly simplifying the lives of PECL extension developers.

In addition, the run-phpt command can be used to run all the extension's phpt test files.

Creating a new PECL package with Pyrus

If you are creating a brand new extension, you should use the generate-ext command to create the basic structure of your extension.

After creating your extension, edit the newly-created CREDITS file to have the correct information:

  
;; extensionname
My Name (myhandle) <myemail@php.net> (lead)
  

Add any additional maintainers using the same format.

Next, edit the README file that describes your package. The first line should be a brief summary of what the extension does, and the rest of the file should be a detailed description of information the user should know about the origin of the extension, and perhaps a simple example of its usage.

Finally, edit the file named RELEASE-0.1.0. Put any release notes in here. Generally initial release is enough information for the first release.

Last, you can optionally create a file named API-0.1.0. Pyrus and the PEAR Installer differentiate between API version and release version, to allow clearly defining an API change or backwards compatibility break. Put information on any API changes into API-0.1.0.

After creating these files, simply run:

php pyrus.phar pickle extensionname

where extensionname is the name of your extension. If you have not yet installed the developer tools, Pyrus will ask if you would like to download and install them. Choose yes and then re-run the command.

Pyrus will create a package.xml and a release called extensionname-0.1.0.tgz, or extensionname-0.1.0.tar if the zlib extension is not enabled. This release can be uploaded to pecl.php.net for immediate distribution.

Note that the directory structure described in pickle command documentation is required for pickle to detect documentation, tests, or data files.

Readying an existing PECL package for Pyrus

To prepare an existing PECL package for Pyrus, you should create all of the information files described in the section Creating a new PECL Package with Pyrus, but instead of creating RELEASE-0.1.0 and API-0.1.0, you would create a file named RELEASE-X.Y.Z where X.Y.Z is the version of the extension. So if your extension's version is 1.2.3 you would create a file named RELEASE-1.2.3. For each of the files above, rather than putting new content, you can copy/paste the existing description, summary and release notes from your existing package.xml. Note that any entities such as &lt; should be converted to their values <, as Pyrus escapes automatically from the text files.

Note that the directory structure described in pickle command documentation is required for pickle to detect documentation, tests, or data files.

Future releases

When the time rolls around for the next release, readying for this is also simple. If you are about to release version 0.2.0, create a file named RELEASE-0.2.0 and put the release notes into the file. Pyrus will automatically detect that 0.2.0 is newer than 0.1.0 and create a new release with those notes.