CHAPTER 12 – THE PACKAGE.XML FORMAT
PEAR packages are released and distributed through gzip-compressed tar files (tarballs). The very first file inside these tarballs is an XML package description file that contains information about the package such as the release version number, which files are included, MD5 checksums for all the files, where they should be installed, and so on.
All this is driven through the XML package description file, called pack- age.xml. Every package has one; it is used when building releases, included in the release tarball, and used by the installer to determine which files go where, among other things. In this section, you learn everything there is to know about the package description format, and how to make your own package description files. Familiarity with XML is assumed.
Package Information Element: <package> Element name: package Attributes: version (mandatory) May occur in: root (mandatory) The package element is the root element of PEAR package description files. The version attribute must contain the file format version, which must be 1.0.
Element: <name> Element name: name Attributes: none May occur in: package (mandatory) maintainer (mandatory) When inside a <package> element, <name> is used for the (case-sensitive) package name. When inside a <maintainer> element, <name> contains the full name of the maintainer.
Element: <summary> Element name: summary Attributes: none May occur in: package (mandatory) The summary element contains a one-liner description of the package.
Element: <description> Element name: description Attributes: none May occur in: package (mandatory) The description element contains a full description of the package. You may use ASCII formatting for this description, and new lines will be preserved. If you indent the description, the indentation will be removed before use.
Element: <license> Element name: license Attributes: none May occur in: package (mandatory) This element tells which software license applies to the package. Use "PHP License" if you do not have any particular preferences.
Element: <maintainers> Element name: maintainers Attributes: none May occur in: package (mandatory) The maintainers (plural) element is just a wrapper for one or more main- tainer (singular) element. Each maintainer element must contain the follow- ing elements: user, role, and name.
Element: <user> Element name: user Attributes: none May occur in: maintainer (mandatory) This is the maintainer's php.net username.
Element: <email> Element name: email Attributes: none May occur in: maintainer (mandatory) This is the maintainer's registered email address.
Element: <role> Element name: role Attributes: none May occur in: maintainer (mandatory) The role element tells what kind of role a maintainer has for the pack- age. The content is a valid role among these: lead. Lead developer or lead maintainer. Only leads may do new releases. developer. A developer does significant contributions regularly, and helps drive the package forward. contributor. Someone who does significant contributions to the package occasionally, and who is credited through status as "contributor." helper. Someone who does occasional minor changes, or someone who has helped out with something at one point, whom the package main- tainer wants to credit.
Element: <release> Element name: release Attributes: none May occur in: package (mandatory) changelog (optional) The release element is a container element for all the release information elements, which we will look at shortly.
Element: <changelog> Element name: changelog Attributes: none May occur in: package (optional) The changelog element may contain one or more release elements with historical information of a package. Typically, when a new release is prepared, the main release element is copied inside the changelog element, before the main release information is altered. This is optional, though; it is up to each package maintainer if he wants to maintain such a changelog in the package definition file, or if he wants to rely on the PEAR web site for changelog. The online changelog is generated from release information for each uploaded release, not from any changelog elements.
Release Information Element: <version> Element name: version Attributes: none May occur in: release (mandatory) This is the release version number. See the "Release Versioning" section earlier in this chapter for details of package/release versioning.
Element: <license> Element name: license Attributes: none May occur in: release (mandatory) This element refers to which license that applies to the package. If in doubt, use "PHP License."
Element: <state> Element name: state Attributes: none May occur in: release (mandatory) This element describes the state of a release; it may have one of the val- ues devel, snapshot, alpha, beta or stable.
Element: <date> Element name: date Attributes: none May occur in: release (mandatory) The release date in ISO-8601 format: YYYY-MM-DD.
Element: <notes> Element name: notes Attributes: none May occur in: release (mandatory) Release notes. It may be indented. The PEAR packager will strip away the common indentation prefix.
Element: <filelist> Element name: filelist Attributes: none May occur in: release (mandatory) This is a wrapper element for <dir> and <file> elements that comprise the actual file list. <filelist> may contain any number of <dir> and <file> elements.
Element: <dir> Element name: dir Attributes: name (mandatory) role (optional) baseinstalldir (optional) May occur in: filelist or dir (both optional) The <dir> element is used to wrap <file> and <dir> elements for files in a subdirectory, and to apply a default baseinstalldir or role to all the files in a directory. The name attribute is mandatory, and contains the directory name. If the role or baseinstalldir attributes are specified, they are used as defaults for every contained <file> element.
Element: <file> Element name: file Attributes: name (required) role (optional) platform (optional) md5sum (optional) install-as (optional) debug (optional) zts (optional) phpapi (optional) zendapi (optional) format (optional) May occur in: filelist or dir (both optional)
The file element is used to associate a file with the package. It has a number of attributes; all but name are optional. A description of each attribute follows in the next few sections.