Section 12.7. The package.xml Format

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

12.7.1.1 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.

12.7.1.2 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.

12.7.1.3 Element: <summary>

Element name:	summary
Attributes:	none
May occur in:	package (mandatory)

The summary element contains a one-liner description of the package.

12.7.1.4 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.

12.7.1.5 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.

12.7.1.6 Element: <maintainers>

Element name:	maintainers
Attributes:	none
May occur in:	package (mandatory)

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.

12.7.1.7 Element: <user>

Element name:	user
Attributes:	none
May occur in:	maintainer (mandatory)

This is the maintainer's php.net username.

12.7.1.8 Element: <email>

Element name:	email
Attributes:	none
May occur in :	maintainer (mandatory)

This is the maintainer's registered email address.

12.7.1.9 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 package. 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 maintainer wants to credit.

12.7.1.10 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.

12.7.1.11 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.

12.7.2. Release Information

12.7.2.1 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.

12.7.2.2 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."

12.7.2.3 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 values devel, snapshot, alpha, beta or stable.

12.7.2.4 Element: <date>

Element name:	date
Attributes:	none
May occur in:	release (mandatory)

The release date in ISO-8601 format: YYYY-MM-DD.

12.7.2.5 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.

12.7.2.6 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.

12.7.2.7 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.

12.7.2.8 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.

12.7.2.9 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.

12.7.2.10 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

• php. PHP source file.

• ext. Binary PHP extension, shared library/DLL.

• src. C/C++ source file.

• test. Regression test file.

• doc. Documentation file.

• Data. Data file; basically anything that does not fit any other role.

• script. Executable script file.

12.7.2.11 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.

12.7.2.12 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.

12.7.2.13 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.

12.7.2.14 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.

12.7.2.15 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.

12.7.2.16 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.

12.7.2.17 Element: <provides>

Element name:	provides
Attributes:	name (required) type (required)
May occur in:	release (optional)

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.

12.7.2.18 name Attribute

This is the name of the entity being described, represented as N in the description of type.

12.7.2.19 type Attribute

The type attribute may have one of the following values:

• ext. Package provides extension N.

• prog. Package provides program N.

• class. Package provides class N.

• function. Package provides function N.

• feature. Package provides feature N.

• api. Package provides the N interface/API.

feature is an abstract type, which lets you specify that "this package provides a way of doing N."