Using Pyrus to create PECL packages
Introduction
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 < 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.