pickle - automatically create a PECL package.xml and package release from source directory

Introduction

The pickle command is designed to make the creation of an extension for PECL developers very easy. It scans a SVN checkout of a PECL package directory, generates package.xml, and packages a release in one step.

The pickle command looks for these standard files:

  • CREDITS
  • README
  • RELEASE-X.Y.Z (where X.Y.Z is the release version)
  • API-X.Y.Z (where X.Y.Z is the API version)

and for a standard directory layout of

/                Extension source files
data/            Data files
tests/           Test files
doc/             Documentation files
examples/        Example files (documentation)

The CREDITS file must have this format for the pickle command to recognize it:

 
;; extensionname
Maintainer One [handle1] <email@example.com> (role)
Maintainer Two [handle2] <email@example.com> (role)
 

Where role is one of lead, developer, contributor, helper. The first line of README is used as the summary of the package. RELEASE-X.Y.Z is used as the release notes.

X.Y.Z in the filename RELEASE-X.Y.Z is also used to automatically calculate the stability, and X.Y.Z in the filename API-X.Y.Z is used to calculate the API stability. The formula is relatively simple: if X is 0, the stability is set to alpha. Otherwise, if X is 1 or greater, the following methods are used to calculate the stability.

  • If Z contains a as in the version 1.0.0a1 the stability is set to alpha

  • If Z contains b as in the version 1.0.0b1 the stability is set to beta

  • If Z contains RC as in the version 1.0.0RC1 the stability is set to beta

  • Otherwise, stability is set to stable.

Arguments to the pickle command

The pickle command has 4 arguments:

php pyrus.phar pickle extname channelname /path/to/packagedir extensions...

/path/to/packagedir specifies the location in which to package up the release. If not present, it defaults to the current working directory. The pickle command usually should be executed from that directory, this argument is present to allow batch creation of package.xml files for multiple extensions with a single shell script.

If package.xml does not exist in the location packaging will take place, then the first argument is required. The first argument is the name of the package, which is usually the same name as the extension, and the second argument is the channel name. If not specified, the package is assumed to be in the pecl.php.net channel.

The final argument, extensions is a list of file extensions that should be considered source files. By default, the file extensions recognized as source files are:

  • c
  • cc
  • h
  • m4
  • w32
  • re
  • y
  • l
  • frag

--donotpackage

If --donotpackage or -n is specified, then the pickle command will only generate package.xml, and will not package up a release. The package command can be used to build the release after reviewing package.xml.