12.7. 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 package.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.
12.7.1. Package Information
188.8.131.52 Element: <package>
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.
184.108.40.206 Element: <name>
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.
220.127.116.11 Element: <summary>
The summary element contains a one-liner description of the package.
18.104.22.168 Element: <description>
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.
22.214.171.124 Element: <license>
This element tells which software license applies to the package. Use "PHP License" if you do not have any particular preferences.
126.96.36.199 Element: <maintainers>
The maintainers (plural) element is just a wrapper for one or more maintainer (singular) element. Each maintainer element must contain the following elements: user, role, and name.
188.8.131.52 Element: <user>
This is the maintainer's php.net username.
184.108.40.206 Element: <email>
This is the maintainer's registered email address.
220.127.116.11 Element: <role>
The role element tells what kind of role a maintainer has for the package. The content is a valid role among these:
18.104.22.168 Element: <release>
The release element is a container element for all the release information elements, which we will look at shortly.
22.214.171.124 Element: <changelog>
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.
12.7.2. Release Information
126.96.36.199 Element: <version>
This is the release version number. See the "Release Versioning" section earlier in this chapter for details of package/release versioning.
188.8.131.52 Element: <license>
This element refers to which license that applies to the package. If in doubt, use "PHP License."
184.108.40.206 Element: <state>
This element describes the state of a release; it may have one of the values devel, snapshot, alpha, beta or stable.
220.127.116.11 Element: <date>
The release date in ISO-8601 format: YYYY-MM-DD.
18.104.22.168 Element: <notes>
Release notes. It may be indented. The PEAR packager will strip away the common indentation prefix.
22.214.171.124 Element: <filelist>
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.
126.96.36.199 Element: <dir>
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.
188.8.131.52 Element: <file>
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.
184.108.40.206 name Attribute
This is the name of the file (for example, "Parser.php"). You may also refer to a file in a subdirectory, in which case the directory part of the file name is also included in the install path.
220.127.116.11 role Attribute
This attribute describes what type of file this is, or what role the file has. Role is optional, and defaults to php. Possible values include
18.104.22.168 platform Attribute
If the platform attribute is specified, the file will be installed on specific platforms. The file will be included in the package regardless of platform, but during installation, the file is skipped if the platform specified in this attribute does not match the host's platform.
Platform names are formatted as operatingsystem-version-cpu-extra. Examples of the operatingsystem fragment are linux, windows, freebsd, hpux, sunos, or irix. Only the operatingsystem fragment is required. The other fragments may be omitted, in which case, the rule will match for any version or variation of the operating system.
The version parameter is taken from the uname r command on UNIX. Linux includes the first two digits of the kernel version, Microsoft Windows uses 9x for Windows 95/98/ME, nt for Windows NT 3.x/4.x, 2000 for Windows 2000, or xp for Windows XP.
The cpu platform fragment is taken from uname m on UNIX, except that all Intel x86 CPUs are represented as i386. Windows is hardcoded to i386 (sorry about that, Windows/alpha users).
Finally, the extra fragment is used for OS variations that affect binary compatibility. Currently, it is used only to differentiate between Linux glibc versions.
22.214.171.124 md5sum Attribute
This is the MD5 checksum of the file. The pear package command automatically creates MD5 checksums of every file included in the package, so it is never necessaryand not recommendedto explicitly set the md5sum attribute.
126.96.36.199 install-as Attribute
If, for some reason, the file should be installed with a different name than the one included in the package, this attribute specifies the alternate file name. Note that install-as does not affect the directory to which the file is copied to, only the base file name used in that directory.
188.8.131.52 debug and zts Attributes
The debug and zts attributes are only set for files with the role attribute set to ext; PHP extension files. Both attributes contain either yes or no, and tell whether the extension binary was built with debug or thread-safety, respectively.
184.108.40.206 phpapi and zendapi Attributes
As with debug and zts, the phpapi and zendapi attributes are also set only for files with role=ext. They describe which versions of the PHP and Zend APIs were used when building the extension binary. PHP does not load extensions that are built with other API versions.
220.127.116.11 format Attribute
The format attribute is used for files with role=doc. It tells which format the documentation is in. Example values include text, dbxml412 (DocBook XML 4.1.2), or xhtml.
18.104.22.168 Element: <provides>
The provides element describes definitions or features that the package provides. The pear package command automatically detects which classes, functions, and methods your package provides, and it embeds this information in a bunch of <provides> elements inside the package tarball's package.xml file.
22.214.171.124 name Attribute
This is the name of the entity being described, represented as N in the description of type.
126.96.36.199 type Attribute
The type attribute may have one of the following values:
feature is an abstract type, which lets you specify that "this package provides a way of doing N."