| 
|
The package definition file package.xml is,
as the name already implies, a well-formed XML file that contains
all information about a PEAR package.
This chapter will describe the allowed elements of the package
definition file and it will discuss how to create such a file for
your package.
The PEAR_PackageFileManager
package simplifies the creation of package.xml.
You can install PEAR_PackageFileManager via the usual command
$ pear install PEAR_PackageFileManager
|
The toplevel element in package.xml is the
element <package version="1.0">. The
allowed sub elements are:
<name>: The name of the package.
<summary>: Short summary of the
package's description.
<description>: Full length description
of the package.
<license>: The license of the package
(LGPL, PHP License etc.).
<maintainers>: Information about the
maintainers of the package.
<release>: Information about the current
release.
<version>: The version number of
the release.
<state>: The state of the release.
(Can be one of stable, beta, alpha, devel, or snapshot.)
<date>: The date when the release has
been rolled.
<license>: The license
under which the code is available.
<notes>: Releasenotes
<filelist>
<deps>: List of dependencies of the
package.
<changelog>: Changelog-like information
about the package.
<release>
<version>: Version of the
specific release.
<state>: State of the specific
release.
<date>: Date when the specific
release has been rolled.
<notes>: Changelog information
The letters allowed inside elements are A-Z and a-z.
Other characters, such as é
must use entities
(in this case: é).
If you create your package.xml files using the
PEAR_PackageFileManager, upgrade your PEAR installation
to version 1.4.0a2 or greater and you won't have
to worry about this because the file manager takes care
of this automatically.
If you write your package.xml files manually, you will
need to enter the entities yourself.
A list of the most common entities can be found at:
http://www.evolt.org/article/A_Simple_Character_Entity_Chart/17/21234/
If the characters you need aren't in that list, go to
http://www.oasis-open.org/docbook/xmlcharent/0.1/index.shtml
and look at the other entity lists.
In order to validate package.xml files one
can use the xmllint tool that comes with
libxml2.
xmllint --dtdvalid http://pear.php.net/dtd/package-1.0 --noout package.xml
Example 15-1. Basic package.xml <?xml version="1.0" encoding="ISO-8859-1" ?>
<package version="1.0">
<name>Money_Fast</name>
<summary>Make money fast.</summary>
<description>
This package helps you to make money pretty fast.
</description>
<license>PHP License</license>
<maintainers>
<maintainer>
<user>foo</user>
<name>Joe Foo</name>
<email>foo@example.com</email>
<role>lead</role>
</maintainer>
</maintainers>
<release>
<version>1.0</version>
<date>2002-05-27</date>
<state>stable</state>
<notes>
This is the first release.
</notes>
<filelist>
<dir name="/" baseinstalldir="Money">
<file role="php">Fast.php</file>
</dir>
</filelist>
</release>
</package> |
|
This package.xml can serve as a template for
you as it already contains all necessary elements. In most cases
you only need to change the character data between the tags in order
to use the example in your package.
Example 15-2. Example for nested directories <?xml version="1.0" encoding="ISO-8859-1" ?>
[...]
<release>
<version>1.0</version>
<date>2002-07-23</date>
<state>stable</state>
<notes>
This is the first release.
</notes>
<filelist>
<dir name="/" baseinstalldir="Money">
<file role="php">Fast.php</file>
<dir name="Calculator" role="php">
<file>Calculator.php</file>
<file>Currency.php</file>
<file>Stocks.php</file>
</dir>
<dir name="docs" role="doc">
<file>README.txt</file>
<file>tutorial.txt</file>
<dir name="examples" role="doc">
<file role="php">NASDAQ.php</file>
<file role="php">DAX.php</file>
</dir>
</dir>
</dir>
</filelist>
</release>
</package> |
|
In this example you get to know a very handy feature: When you
have a directory in your package that only contains files of
the same type, you can add to role attribute even to the
<dir> tag instead of adding it to every
single <file> tag.
With the knowledge you aquired during this chapter you should now
be able to produce a package definition file for your own package.
If you still have questions concerning the topic, don't hesitate
to ask on the mailinglist.
The role-attribute in the <file> tag
defines what type the file has and in which location it should
be installed.
Table 15-1. Possible values | Value | | Destination dir |
|---|
| php | PHP source file | the directory is determined by the package name | | ext | Extension, dynamically loadable library | the PHP extension directory or
PHP_PEAR_EXTENSION_DIR
if defined | | doc | Documentation file | {PEAR_documentation_dir}/Package_Name/ | | data | Package related data files (graphics, data tables etc) | {PEAR_data_dir}/Package_Name/ | | test | Package related test files (unit-tests etc) | {PEAR_test_dir}/Package_Name/ | | script | Package related shell scripts | the PHP binary directory or
PHP_PEAR_BIN_DIR
if defined | | src and extsrc | C or C++ source code | not copied directly - used to build a
extension |
The PEAR Package Manager supports checking for
different system capabilities. You define those
dependencies with the <dep> tag:
The following types are supported:
Table 15-2. type values | Value | | Meaning | Example |
|---|
| pkg | Package | depends on a certain Package | "HTML_Flexy" | | ext | Extension | depends on a certain PHP extension | "curl" | | php | PHP | depends on a certain PHP version | "4.2" | | prog | Program |
depends on a certain Program avaible in the
system path. This is not supported in the PEAR installer.
| "latex" | | os | Operating System | depends on a certain OS version | "Linux" | | sapi | Server API | depends on a certain Server API. This is not supported in the PEAR installer. | "Apache" | | zend | Zend | depends on a certain version of the Zend API.
This is not supported in the PEAR installer. | "2" |
| Warning |
The DTD for the package definition file supports
further types, but those are not supported yet.
|
The rel-attribute
defines the relationship between the existing
capability and the required.
Table 15-3. rel values | Value | | Meaning | Can be used with |
|---|
| has | has |
the existing capability must have the
requirement - version-attribute is
ignored
| pkg, ext, php, prog, os, sapi, zend | | eq | equal |
the the existing capability must exactly match the
version value
| pkg, ext, php, prog, os, sapi, zend | | lt | less than |
the existing capability must be less than the version value
| pkg, ext, php, zend | | le | less than or equal |
the existing capability must be less than or equal to the
version value
| pkg, ext, php, zend | | gt | greater than |
the existing capability must be greater than the version
value
| pkg, ext, php, zend | | ge | greater than or equal |
the existing capability must greater than or equal to the
version value
| pkg, ext, php, zend | | not | conflicting dependency |
the dependency conflicts with the package, the two cannot co-exist.
version is ignored.
| ext, php |
Has will be used if no other value has been
defined. Note that rel is required in PEAR 1.4.0 and newer.
The attribute version defines the version
that is used to compare.
The attribute optional can be used when
a dependency is not required but having the package installed
can bring enhanced functionalities. The only legal values are "yes"
and "no". If the optional attribute is not present, a dependency is
required.
When optional="yes" is used, this attribute
will result in installation messages similar to the following messages:
$ pear install <package>
Optional dependencies:
Package `XML_Tree' is recommended to utilize some features.
Package `MDB' is recommended to utilize some features.
|
|
|
 |
|
|
