
       +----------+-----------------------------------------+
       |    Title | Usage of the PEAR Package Manager       |
       +----------+-----------------------------------------+
       |  Authors | Tomas V.V.Cox <cox@idecnet.com>         |
       |          | Michael Haertl <mhaertl@pressline.de>   |
       +----------+-----------------------------------------+
       | Revision | $Revision$                        |
       +----------+-----------------------------------------+


!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
The intented audience for this document is for the people who
wants to test the system. This is not the final doc and it may
contain errors or parts that will be changed in the future
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


================================================================
1. Introduction
================================================================


PEAR consists of a base installation which contains all basic classes
needed by PEAR, and further seperate packages which can be
separately installed from a central repository (http://pear.php.net)
according to requirements. Every package is maintained by its own
development team and has its own release cycles - independent from
the PEAR base installation.

Presently the PEAR Package Manager can install packages, create them,
manage a registry of installed packages, check dependencies, interact
with a xml-rpc service and a bunch of other things.

Since at the time of writing most parts of PEAR are still in
development stage we will extensively cover the installation of the
Package Manager from CVS. The PEAR Package Manager is included with
the main PHP distribution.


================================================================
2. Getting the PEAR Package Manager
================================================================


The requirements to use the Package Manager are:

- PHP Interpreter (CGI-Version) is available
- the PEAR files from php4/pear/ CVS are installed
- possibly Archive/Tar.php has to be copied manually

Installation of the CGI version of PHP is well documented in the PHP
manual, chapter 2. So we will not cover it here.

The CVS module of php holds two different PEAR directories.
"php4/pear/" is the module which will go into the next release of PHP.
In the future this will only contain the PEAR base modules including
the Package Manager and the core components. All new PEAR projects
go into the "pear/" module and all other elements from "php4/pear"
will migrate to "pear/".

The "php4/pear/" tree can be fetched from CVS with these commands:

    # login to CVS
    cvs -z3 -d :pserver:cvsread@cvs.php.net:/repository login
    Password: [use "phpfi" as password]
    # fetch the php4/pear tree
    cvs -z3 -d :pserver:cvsread@cvs.php.net:/repository co php4/pear

After this you can find the PEAR files in php4/pear.

If you have already installed PEAR you should replace your PEAR
installation with the files from CVS. If you haven't, you should
choose a path for PEAR which depends on your system. (on LINUX it's
usually /usr/local/lib/php/).

If you installed PEAR the first time you will also have to add the
PEAR install path to your include_path in php.ini.

The Package Manager also needs the file Archive/Tar from the
pear/ module. Since the CVS is updated regularly you probably already
have this file in your PEAR install path. If you haven't, you can
fetch this file with:

    cvs -z3 -d :pserver:cvsread@cvs.php.net:/repository co \
    pear/Archive_Tar/Tar.php

Copy it to PATH_TO_PEAR/Archive/Tar.php manually.

The Package Manager itself can be found in the PEAR install path,
too:

    PATH_TO_PEAR/scripts/pear.in

Copy this file somewhere into your search path (on Linux
/usr/local/bin would be a good choice) and rename it to 'pear'. After
all you have to set the correct path to the PHP interpreter in the
first line of this script. On Linux this  usually would be:

    #!/usr/local/bin/php -Cq

Now the Package Manager is ready for use an can be started by
entering 'pear'. If you run it without arguments you should get a
short help which will look like:

    Usage: pear [options] command [command-options] <parameters>
    Options:
         -v         increase verbosity level (default 1)
         -q         be quiet, decrease verbosity level
         -c file    find user configuration in `file'
         -C file    find system configuration in `file'
         -d foo=bar set user config variable `foo' to `bar'
         -D foo=bar set system config variable `foo' to `bar'
         -s         store user configuration
         -s         store system configuration
         -u foo     unset `foo' in the user configuration
         -h, -?     display help/usage (this message)
    Commands:
       help [command]
       install [-r] <package file>
       uninstall [-r] <package name>
       package [package info file]
       list-installed
       list-available
       info
       show-config

================================================================
3. Install packages from http://pear.php.net
================================================================

As simple as:

    pear install http://pear.php.net/get/HTTP_Upload

That will install the lastest version of the package HTTP_Upload
in your system.

If you don't know the name or want to browse the avaible packages,
point your web browser to http://pear.php.net and use the Package
Browser. Once you find the package you want to download, copy the
url location and launch the above command. Of course you can
download the package manually and install it locally.

Currently the whole system is working in BETA state.


================================================================
4. Install packages from CVS
================================================================

You already can create and install packages from most of the
sub-projects from the CVS pear/. Therefore you will need the complete
PEAR tree:

    cvs -z3 -d :pserver:cvsread@cvs.php.net:/repository co pear/

In the pear/ directory every sub-project has it's own subdirectory.
Please note that the directory structure in the CVS differs from that
of the later PEAR installation.

To create a package from a sub-project, call pear like this:

    pear package path_to_project/package.xml

Example:

    # create and install the package for the QuickForm package
    pear package HTML_QuickForm/package.xml
    pear install HTML_QuickForm-1.4.tgz


================================================================
5. Creating your own packages
================================================================


To enhance team work of developers, PEAR provides them with a pear/
directory in the CVS module at cvs.php.net. But the directory
structure there differs from that of the later PEAR installation.

To ensure scalability in terms of the number of developers, every
PEAR sub-project has its own directory. For example a 'Net' project,
that should supply all classes for networking you can think of, would
probably become to big for a small group of developers which only may
want to contribute a Whois package.

Therefore all sub-projects for "Net" are located directly under
pear/. For Whois this would be Net_Whois. That way the package
Net_Whois can be developed and installed independently.

At install time these files will be copied into the PEAR install
path. The package Net_Whois then can be found in PATH_TO_PEAR/Net/.

The core of a sub project is the XML file package.xml. It describes
the contents of a package. An example shall explain how this works.

Suppose your project has a directory structure like this in CVS:

    <actual path>
    |
    +---Net_Whois/
        |
        +---package.xml // This file must be present in
        |               // the base dir of every package
        +---Whois.php
        +---docs/
            |
            +---Whois_usage.txt


The according package.xml would look like this:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<package>

    <!-- Package description -->

    <name>Net_Whois</name>
    <summary>A tool for querying Whois Servers</summary>
    <description>
    The PEAR::Net_Whois class
    provides a tool for querying Whois Servers
    </description>

    <!-- Authors -->

    <maintainers>
        <maintainer>
            <user>SN</user> <!-- php cvs user -->
            <name>Sebastian Nohn</name>
            <email>sebastian@nohn.net</email>
            <role>lead</role> <!-- 'lead','developer','contributor','helper' -->
        </maintainer>
    </maintainers>

    <!-- Current release -->

    <release>

        <!-- Release details -->

        <version>0.1</version>
        <state>beta</state>   <!-- 'alpha','beta','stable','snapshot' -->
        <date>2001-08-22</date>
        <notes> This is the initial independent release of
        the Net_Whois package.
        </notes>

        <!-- Dependencies -->

        <deps></deps> <!-- see point 6. -->

        <!-- Files -->

        <filelist>
            <dir name="/" BaseInstallDir="Net">
                <file role="php">Whois.php</file>
                <dir name="docs" role="docs">
                    <file>Whois_usage.txt</file>
                </dir>
            </dir>
        </filelist>
    </release>
</package>

The upper part is self explanatory. It contains summary, version and
maintainer information. The bottom part lists all contained files:

    <filelist>
        <dir name="/" BaseInstallDir="Net">
            <file role="php">Whois.php</file>
            <dir name="docs" role="docs">
                <file>Whois_usage.txt</file>
            </dir>
        </dir>
    </filelist>

<dir name="/" BaseInstallDir="Net"> specifies, where the package
should be installed. "/" stands here for the base PEAR install path.
With BaseInstallDir you can define the destination dir inside this
path.

<file role="php">Whois.php</file> specifies that the file type for
Whois.php is "php". It must be one of "php" for source files, "docs"
for documentation or "test" for test files. Test files will not be
installed. Since this tag is contained inside the previous <Dir ..>
tag, Whois.php will be installed to PATH_TO_PEAR/Net. Files marked
with "doc" role, will be installed in a PEAR central doc directory
at PHP_DATADIR/pear/doc/Package_name, in the example could be
/usr/local/share/php/pear/doc/Net_Whois/.

A subdir is specified with <dir name="docs" role="docs">. A directory
also has one of the mentioned types. In this case it will be of type
"docs". All files in this directory inherit this type if not
specified otherwise.

This package will therefore be installed like this to the PEAR
install path:

    <PATH_TO_PEAR>
    |
    +---Net/
        |
        +---Whois.php

    <PHP_DATADIR/pear/doc/Net_Whois>
    |
    +---docs/
        |
        +---Whois_usage.txt


================================================================
6. Specifying dependencies in package.xml
================================================================

Please refer to the Dependencies RFC document located at:
http://cvs.php.net/cvs.php/pearweb/rfc/003-dependencies.txt
