cvs: pearweb /doc pear_package_manager.txt
| From: | Thomas V.V.Cox | Date: | Wed, 19 Dec 2001 01:56:53 +0000 |
| Subject: | cvs: pearweb /doc pear_package_manager.txt | ||
| Groups: | php.pear.cvs | ||
| Request: | Send a blank email to pear-cvs+get-1620@lists.php.net to get a copy of this message | ||
cox Tue Dec 18 20:56:53 2001 EDT
Added files:
/pearweb/doc pear_package_manager.txt
Log:
Initial unofficial doc for "Usage of the PEAR Package Manager"
Index: pearweb/doc/pear_package_manager.txt +++ pearweb/doc/pear_package_manager.txt +----------+-----------------------------------------+ | Title | Usage of the PEAR Package Manager | +----------+-----------------------------------------+ | Authors | Tomas V.V.Cox <cox@idecnet.com> | | | Michael Haertl <mhaertl@pressline.de> | +----------+-----------------------------------------+ | Revision | $Revision: 1.1 $ | +----------+-----------------------------------------+ !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! The intented audience for this document if 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 bounch 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. Installing from CVS ================================================================ 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. ================================================================ 3. Usage with CVS packages ================================================================ In the future you will be able to install PEAR packages from http://pear.php.net with a single command line like this: # Install the HTML_QUICKFORM package pear install \ http://pear.php.net/packages/HTML_QUICKFORM-1.4.tgz Currently there are no packages available yet on the PEAR website. But you already can create and install packages from most of the sub-projects form 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 ================================================================ 4. 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: <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> <name>Net_Whois</name> <summary> The PEAR::Net_Whois class provides a tool for querying Whois Servers </summary> <maintainers> <maintainer> <user>SN</user> <name>Sebastian Nohn</name> <email>sebastian@nohn.net</email> </maintainer> </maintainers> <release> <version>0.1</version> <date>2001-08-22</date> <notes> This is the initial independent release of the Net_Whois package. </notes> <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. 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 +---docs/ | +---Whois_usage.txt ================================================================ 5. 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
Index: pearweb/doc/pear_package_manager.txt +++ pearweb/doc/pear_package_manager.txt +----------+-----------------------------------------+ | Title | Usage of the PEAR Package Manager | +----------+-----------------------------------------+ | Authors | Tomas V.V.Cox <cox@idecnet.com> | | | Michael Haertl <mhaertl@pressline.de> | +----------+-----------------------------------------+ | Revision | $Revision: 1.1 $ | +----------+-----------------------------------------+ !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! The intented audience for this document if 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 bounch 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. Installing from CVS ================================================================ 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. ================================================================ 3. Usage with CVS packages ================================================================ In the future you will be able to install PEAR packages from http://pear.php.net with a single command line like this: # Install the HTML_QUICKFORM package pear install \ http://pear.php.net/packages/HTML_QUICKFORM-1.4.tgz Currently there are no packages available yet on the PEAR website. But you already can create and install packages from most of the sub-projects form 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 ================================================================ 4. 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: <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> <name>Net_Whois</name> <summary> The PEAR::Net_Whois class provides a tool for querying Whois Servers </summary> <maintainers> <maintainer> <user>SN</user> <name>Sebastian Nohn</name> <email>sebastian@nohn.net</email> </maintainer> </maintainers> <release> <version>0.1</version> <date>2001-08-22</date> <notes> This is the initial independent release of the Net_Whois package. </notes> <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. 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 +---docs/ | +---Whois_usage.txt ================================================================ 5. 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