Chapter 10. The package definition file `package.xml`

Table of Contents
Introduction to the package definition file package.xml

Introduction to the package definition file `package.xml`

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

Allowed elements

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.)
<release>: Information about the current release.
<changelog>: Changelog-like information about the package.
- <release>
<deps>: List of dependencies of the package.
- <dep type="xxx" rel="yyy" optional="yes">name</dep> : For more information about dependencies, please see below.

Creating a package definition file

Example 10-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>  <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 10-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 file roles

The role-attribute in the <file> tag defines what type the file has and in which location it should be installed.

Table 10-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 (grapics etc)	{PEAR_data_dir}/Package_Name/
test	Package related data files (grapics 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

Defining Dependencies

The PEAR Package Manager supports checking for different system capabilities. You define those dependencies with the <dep> tag:

Example 10-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.

<?xml version="1.0" encoding="ISO-8859-1" ?>  [...]  </release>  <deps>   <dep type="php" rel="ge" version="4.3.0" />   <dep type="pkg" rel="has" version="1.0">XML_Parser</dep>  </deps> </package>

The `type`-attribute

The following types are supported:

Table 10-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

The rel-attribute defines the relationship between the existing capability and the required.

Table 10-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 `version`-attribute

The attribute version defines the version that is used to compare.

The `optional`-attribute

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.