Current File : //opt/RZphp72/includes/www/pear.php.net/rfc/003-dependencies.txt

Title:         Dependencies in PEAR Packages
Version:       $Revision$
Status:        proposal
Maintainer:    Stig S. Bakken <ssb@fast.no>
Created:       2001-08-28
Modified:      2001-09-06

1. Introduction

This document describes how PEAR should manage dependencies between
packages, or between packages and external components, operating
environment and other factors.

2. Dependency Phases

There are three phases where dependencies need to be considered:

 * When a package is built (for packages with C code)

 * When a package is installed

 * When a package is used

When building a package, there may be dependencies to external
libraries, to a certain PHP version or maybe to a specific operating
system or web server.  If the dependencies in this phase are not
satisfied, we'll never get to the next phase.

When installing a package, there may also be dependencies to external
libraries, especially if it contains a C extension linked with a
shared library.  The most typical install-time dependencies are to
have another package installed, to have a bundled PHP feature enabled
or to have a specific or minimum PHP version.

Finally there are run-time dependencies.  Hopefully everything should
be working fine when we get here, but there may be some code that
relies on configuration options that may be changed run-time, and the
installer has no way of checking that.  Run-time dependencies should
be handled much more gracefully than build/install-time ones, applying
workarounds wherever possible.  Php.ini options are typical examples
of run-time dependencies: whether the URL fopen wrappers are enabled,
whether PHP is running in safe mode, and so on.

3. Dependency Types

These are the different types of dependencies we would like to
support:

 Type      Relation   Description
+---------+----------+---------------------------------------------------+
|pkg      | has      |another PEAR package installed                     |
|pkg      | v.eq     |specific version of another PEAR package installed |
|pkg      | v.ge     |minimum version of another PEAR package installed  |
|ext      | has      |bundled PHP extension available                    |
|ext      | v.eq     |specific version of PHP with bundled extension     |
|ext      | v.gt     |minimum version of PHP with bundled extension      |
|php      | v.eq     |specific version of PHP                            |
|php      | v.ge     |minimum version of PHP                             |
|prog     | has      |external program                                   |
|ldlib    | has      |external library for linking                       |
|rtlib    | has      |external runtime library                           |
|os       | has      |operating system                                   |
|websrv   | has      |web server                                         |
|websrv   | v.eq     |specific version of web server                     |
|websrv   | v.ge     |minimum version of web server                      |
|sapi     | has      |SAPI backend                                       |
|sapi     | v.eq     |specific version of PHP with SAPI backend          |
|sapi     | v.ge     |minimum version of PHP with SAPI backend           |
+---------+----------+---------------------------------------------------+

[[ 2001-12-12 cox ]]

4. Declaring dependencies in the PEAR package definition file

Proposed notation for package.xml:

<release>
	<version>...</version>
	<..>...</..>
	<deps>
		<!-- type: one of the types mentioned in point 3.
		     rel : "has", or any version_compare() valid comparison
			   operator
		     version: a version number according to the PHP
		              versioning scheme -->
		<dep type="xxx" rel="xx" version="x.x.x">name</dep>
	</deps>
</release>

Usage example:

<release>
	<version>1.3</version>
	<date>2001-04-19</date>
	<notes>Bugfix release</notes>
	<deps>
		<!-- needed a version of the HTML_Common PEAR package
	     greater or equal than version 0.6.3 -->
		<dep type="pkg" rel="ge" version="0.6.3">HTML_Common</dep>

		<!-- The GD php extension has to be present -->
		<dep type="ext">gd</dep>
		
		<!-- The OS (valid PHP_OS php constant values, for ex:
		     linux, win32, winnt) -->
		##(cox) What about if I need only in Windows?
		##      Perhaps use PEAR_OS (unix|windows) instead?
		##      Dependencies operators? if (win32||winnt)
		<dep type="os">linux</dep>
		
		<!-- The minimun version of php needed is 4.1 -->
		<dep type="php" rel="ge" version="4.1" />
		
		<!-- The SAPI backend -->
		##(cox) The sapi at installation time will be always
		##      the cgi. We can't check if the user has
		##      installed a SAPI or not apart from the installer
		##      SAPI.
		<dep type="sapi">cgi</dep>
		
		<!-- The program "grep" is present in the PATH -->
		<dep type="prog">grep</dep>

	</deps>
</release>

## TODO:
## - provide examples for all the dependencies types
## - resolve conflicts
##

[[ end 2001-12-12 cox ]]