PEAR Manual
Prev |  | Next

# Chapter 16. The package definition file `package.xml`, version 2.0

# A quick and dirty guide to version 2.0 of 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. Version 2.0 contains several important enhancements over version 1.0, including

- Channel support

- Binary PECL packages support (not fully implemented in PEAR 1.4.0)

- More specific dependency resolution

For those of you with an existing package.xml version 1.0, you can create an approximate equivalent package using the

    $ pear convert

command. Note that as of version 1.6.0a1, PEAR_PackageFileManager supports package.xml 2.0 with the PEAR_PackageFileManager2 class.

PECL developers: for more information on pecl-specific features, read here.

## An example file with all elements

    <?xml version="1.0"?>
    <package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0"
        xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://pear.php.net/dtd/tasks-1.0
    http://pear.php.net/dtd/tasks-1.0.xsd
    http://pear.php.net/dtd/package-2.0
    http://pear.php.net/dtd/package-2.0.xsd">
     <name>PEAR</name>
     <channel>pear.php.net</channel>
     <summary>Any one-line summary</summary>
     <description>any static long description.
     This text should not change very much between releases, use the "notes" tag
     for release notes
     </description>
     <lead>
      <name>Greg Beaver</name>
      <user>cellog</user>
      <email>cellog@php.net</email>
      <active>yes</active>
     </lead>
     <date>2005-02-26</date>
     <time>20:30:13</time> <-- note: <time> is optional -->
     <version>
      <release>1.4.0a2</release>
      <api>1.4.0</api>
     </version>
     <stability>
      <release>alpha</release>
      <api>alpha</api>
     </stability>
     <license uri="http://www.php.net/license">PHP License</license>
     <notes>
     Put release notes here.
     They can be multi-line
     </notes>
     <contents>
      <dir name="/">
       <dir name="PEAR">
        <dir name="ChannelFile">
         <file name="Parser.php" role="php" />
        </dir> <!-- /PEAR/ChannelFile -->
        <file name="Dependency2.php" role="php">
         <tasks:replace from="@PEAR-VER@" to="version" type="package-info"/>
        </file>
       </dir> <!-- /PEAR -->
       <dir name="scripts" baseinstalldir="/">
        <file name="pear.bat" role="script">
         <tasks:replace from="@bin_dir@" to="bin_dir" type="pear-config" />
         <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
         <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
         <tasks:windowseol/>
        </file>
        <file name="pecl.bat" role="script">
         <tasks:replace from="@bin_dir@" to="bin_dir" type="pear-config" />
         <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
         <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
         <tasks:windowseol/>
        </file>
        <file name="pear.sh" role="script">
         <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
         <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
         <tasks:replace from="@pear_version@" to="version" type="package-info" />
         <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
         <tasks:unixeol/>
        </file>
        <file name="pecl.sh" role="script">
         <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
         <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
         <tasks:replace from="@pear_version@" to="version" type="package-info" />
         <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
         <tasks:unixeol/>
        </file>
        <file name="pearcmd.php" role="php">
         <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
         <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
         <tasks:replace from="@pear_version@" to="version" type="package-info" />
         <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
        </file>
        <file name="peclcmd.php" role="php">
         <tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
         <tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
         <tasks:replace from="@pear_version@" to="version" type="package-info" />
         <tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
         <tasks:footask/>
        </file>
       </dir> <!-- /scripts -->
       <file name="package.dtd" role="data" />
       <file name="postinstall.php" role="php">
        <tasks:postinstallscript/>
       </file>
       <file name="template.spec" role="foo" />
      </dir> <!-- / -->
     </contents>
     <compatible>
      <name>FooPackage</name>
      <channel>pear.php.net</channel>
      <min>1.3.0</min>
      <max>1.5.0</max>
     </compatible>
     <dependencies>
      <required>
       <php>
        <min>4.2</min>
        <max>6.0.0</max>
       </php>
       <pearinstaller>
        <min>1.4.0dev13</min>
       </pearinstaller>
       <package>
        <name>Archive_Tar</name>
        <channel>pear.php.net</channel>
        <min>1.1</min>
        <recommended>1.2</recommended>
       </package>
       <package>
        <name>Foo</name>
        <uri>http://www.example.com/Foo-1.2.0.tgz</uri>
       </package>
       <extension>
        <name>xml</name>
       </extension>
       <os>
        <name>windows</name>
        <conflicts/>
       </os>
       <arch>
        <pattern>*-i?86-*-*</pattern>
       </arch>
      </required>
      <optional>
       <package>
        <name>PEAR_Frontend_Web</name>
        <channel>pear.php.net</channel>
        <min>0.5.0</min>
       </package>
       <package>
        <name>PEAR_Frontend_Gtk</name>
        <channel>pear.php.net</channel>
        <min>0.4.0</min>
       </package>
      </optional>
      <group name="remoteinstall" hint="adds the ability to install packages to a remote ftp server">
       <package>
        <name>Net_FTP</name>
        <channel>pear.php.net</channel>
        <min>1.3.0RC1</min>
        <recommended>1.3.0</recommended>
       </package>
      </group>
      <group name="webinstaller" hint="PEAR's web-based installer">
       <package>
        <name>PEAR_Frontend_Web</name>
        <channel>pear.php.net</channel>
        <min>0.5.0</min>
       </package>
      </group>
      <group name="gtkinstaller" hint="PEAR's PHP-GTK-based installer">
       <package>
        <name>PEAR_Frontend_Gtk</name>
        <channel>pear.php.net</channel>
        <min>0.4.0</min>
       </package>
      </group>
     </dependencies>
     <usesrole>
      <role>foo</role>
      <package>Foo</package>
      <channel>pear.example.com</channel>
     </usesrole>
     <usestask>
      <task>footask</task>
      <package>Footask</package>
      <channel>pear.example.com</channel>
     </usestask>
     <phprelease>
      <installconditions>
       <os>
        <name>windows</name>
       </os>
      </installconditions>
      <filelist>
       <install as="pear.bat" name="scripts/pear.bat" />
       <install as="pecl.bat" name="scripts/pecl.bat" />
       <install as="pearcmd.php" name="scripts/pearcmd.php" />
       <install as="peclcmd.php" name="scripts/peclcmd.php" />
       <ignore name="scripts/pear.sh" />
       <ignore name="scripts/pecl.sh" />
      </filelist>
     </phprelease>
     <phprelease>
      <filelist>
       <install as="pear" name="scripts/pear.sh" />
       <install as="pecl" name="scripts/pecl.sh" />
       <install as="pearcmd.php" name="scripts/pearcmd.php" />
       <install as="peclcmd.php" name="scripts/peclcmd.php" />
       <ignore name="scripts/pear.bat" />
       <ignore name="scripts/pecl.bat" />
      </filelist>
     </phprelease>
     <changelog>
      <release>
       <version>
        <release>1.3.5</release>
        <api>1.3.0</api>
       </version>
       <stability>
        <release>stable</release>
        <api>stable</api>
       </stability>
       <date>2005-02-26</date>
       <license uri="http://www.php.net/license/3_0.txt">PHP License</license>
       <notes>
     * fix Bug #3505: pecl can't install PDO
     * enhance pear run-tests dramatically
     * fix Bug #3506: pear install should export the pear version into the environment

       </notes>
      </release>
      <release>
       <version>
        <release>1.4.0a1</release>
        <api>1.4.0</api>
       </version>
       <stability>
        <release>alpha</release>
        <api>alpha</api>
       </stability>
       <date>2005-02-26</date>
       <license uri="http://www.php.net/license/3_0.txt">PHP License</license>
       <notes>
      This is a major milestone release for PEAR.  In addition to several killer features,
      every single element of PEAR has a regression test, and so stability is much higher
      than any previous PEAR release, even with the alpha label.

      New features in a nutshell:
      * full support for channels
      * pre-download dependency validation
      * new package.xml 2.0 format allows tremendous flexibility while maintaining BC
      * support for optional dependency groups and limited support for sub-packaging
      * robust dependency support
      * full dependency validation on uninstall
      * support for binary PECL packages
      * remote install for hosts with only ftp access - no more problems with
        restricted host installation
      * full support for mirroring
      * support for bundling several packages into a single tarball
      * support for static dependencies on a url-based package

      Specific changes from 1.3.5:
      * Implement request #1789: SSL support for xml-rpc and download
      * Everything above here that you just read
       </notes>
      </release>
     </changelog>
    </package>

Prev | Home | Next
The package definition file `package.xml` | Up | Special information for PECL developers