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.
Post a Comment