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.
maintainer: Information about a single maintainer. (May be used multiple times.)
<user>: The account name of the user.
<role>: The role the user has during package development. (Can be either lead, developer, helper.)
<name>: The realname of the user.
<email>: The email address of the user.
<release>: Information about the current release.
<version>: The version number of the release.
<state>: The state of the release. (Can be one of stable, dev, beta, alpha, devel, or snapshot.)
<date>: The date when the release has been rolled.
<notes>: Releasenotes
<filelist>
<file role="xxx">: Filename
<dir name="xxx" [role="xxx"]>: Name of a subdirectory. This subdirectory can again contain <file role="xxx"> entries.
<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
<deps>: List of dependencies of the package.
<dep type="xxx" rel="yyy" optional="yes">name</dep> : For more information about dependencies, please see below.
Example 14-1. Basic package.xml
|
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 14-2. Example for nested directories
|
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 14-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:
Example 14-3. package.xml with dependencies The following example shows how to specificy dependencies for PHP 4.3.0 or better and XML_Parser 1.0.
|
The following types are supported:
Table 14-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 | "latex" |
| os | Operating System | depends on a certain OS version | "Linux" |
| sapi | Server API | depends on a certain Server API | "Apache" |
| zend | Zend | depends on a certain version of the Zend API | "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 14-3. rel values
| Value | Meaning | Can be used with | |
|---|---|---|---|
| has | has | the existing capability must have the requirement - version-attribute is not required | 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 then | 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 |
Has will be used if no other value has been defined.
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.
|