Introduction to the package definition file package.xml

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, 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>

    • <file name="xxx" role="xxx" />: Filename
    • <dir name="xxx" [role="xxx"]>: Name of a subdirectory. This subdirectory can again contain <file role="xxx"> entries.

  • <deps>: List of dependencies of the package.

    • <dep type="xxx" rel="yyy" optional="yes">name</dep> : For more information about dependencies, please see below.

• <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

<?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" name="Fast.php" />
   </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.

<?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" name="Fast.php" />
    <dir name="Calculator">
     <file name="Calculator.php" role="php" />
     <file name="Currency.php" role="php" />
     <file name="Stocks.php" role="php" />
    </dir>
    <dir name="docs">
     <file name="README.txt" role="doc" />
     <file name="tutorial.txt" role="doc" />
     <dir name="examples">
      <file name="NASDAQ.php" role="php" />
      <file name="DAX.php" role="php" />
     </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've acquired from 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.

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

<?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>

      
$ pear install <package>
Optional dependencies:
Package `XML_Tree' is recommended to utilize some features.
Package `MDB' is recommended to utilize some features.