svn: /pear/peardoc/trunk/ en/guide/users/dependencytracking.xml manual.xml

Added: pear/peardoc/trunk/en/guide/users/dependencytracking.xml
===================================================================
--- pear/peardoc/trunk/en/guide/users/dependencytracking.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/guide/users/dependencytracking.xml	2009-08-31 08:12:07 UTC (rev 287910)
@@ -0,0 +1,256 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet" xml:id="guide.users.dependencytracking">
+    <info><title>Dependency Tracking (Meta Packages) with PEAR</title></info>
+
+    <para>
+    The PEAR installer can be used for tracking project dependencies with a simple
+    package definition file, without having to describe the entire project in that file.
+    </para>
+
+    <para>
+    This can be done, for example, to ensure that a specified set of PEAR packages
+    are installed on both a development environment, into a test environment and
+    finally into a production environment with minimum fuss.
+    </para>
+
+    <para>
+    Another reason for using pear to track dependencies is to reduce the amount of
+    work required when trying to do this work manually: checking to see if a new
+    release that may add required functionality, close security issues or include bug fixes can take time. Add a
+    few more packages and interdependencies in to the mix and the amount of work grows exponentially.
+    </para>
+
+    <para>
+    The PEAR installer can take care of all of this for you. You just need to tell it what you want.
+    </para>
+
+    <section xml:id="guide.users.dependencytracking.whattodo">
+        <title>What to do</title>
+        <para>
+        The logical steps for creating a package definition file, typically named
+        package.xml, that describes the dependencies required by your project are:
+
+        <orderedlist>
+        <listitem>
+        List what you need -
+        Include in this details such as what channels the packages are to be
+        installed from and whether you only very specific versions of those packages
+        to be installed, or if you want to specify what the minimum versions of the
+        packages should be.
+        </listitem>
+        <listitem>
+        Create a package.xml including these packages as it's manifest.
+        </listitem>
+        <listitem>
+        Test that it works
+        </listitem>
+        </orderedlist>
+        </para>
+    </section>
+
+    <section xml:id="guide.users.dependencytracking.generatingalist">
+        <title>Generating a list of what's needed</title>
+        <para>
+        Assuming you want to replicate a subset of [pear] packages that are on one
+        machine and you wish to install that same set on another machine, this is one
+        suggested way to get the required details:
+        Use the output of "$ pear info -a" to determine the names of the packages,
+        which versions are installed and what channels they were installed from.
+        </para>
+        <para>
+        For example (edited for brevity):
+        </para>
+
+        <para>
+            <screen>
+            <![CDATA[
+        Installed packages, channel doc.php.net:
+        ========================================
+        Package Version State
+        PhD     0.4.6   beta
+
+        Installed packages, channel pear.php.net:
+        =========================================
+        Package                         Version   State
+        PEAR                            1.8.1     stable
+        PEAR_Size                       0.1.9     alpha
+        PHP_Beautifier                  0.1.14    beta
+        PHP_CodeSniffer                 1.2.0RC1  beta
+        PHP_CompatInfo                  1.9.0     stable
+        PHP_UML                         0.5.2     alpha
+        PhpDocumentor                   1.4.2     stable
+        Testing_Selenium                0.4.3     beta
+
+
+        Installed packages, channel pear.phpunit.de:
+        ============================================
+        Package Version State
+        PHPUnit 3.3.16  stable
+        phpcpd  1.1.1   stable
+            ]]>
+            </screen>
+        </para>
+    </section>
+
+
+
+    <section xml:id="guide.users.dependencytracking.generatingpackagexml">
+        <title>Writing/Generating the package.xml</title>
+        <para>
+        The package.xml can be generated using the pfm tool or in your favourite text editor.
+        It's your call really.
+        </para>
+
+        <para>
+        The pfm tool can be installed via:
+            <screen>
+            <![CDATA[
+        $pear install PEAR_PackageFileManager_Cli
+            ]]>
+            </screen>
+        </para>
+
+        <section xml:id="guide.users.dependencytracking.generatingpackagexml">
+            <title>Creating package.xml Using PFM</title>
+            <para>
+            pfm is a commandline tool that analyses the contents of a project directory and creates a package.xml describing what it has found.
+            Because we don't want to install any project specific files we're going to cheat in order to keep the generated package.xml as small as possible.
+            </para>
+
+            <para>
+            Begin by creating an empty directory and then moving into it:
+            </para>
+
+            <para>
+                <screen>
+                <![CDATA[
+            kguest:~$ cd MyProject-packages
+            /home/kguest/MyProject-packages
+                ]]>
+                </screen>
+            </para>
+
+            <para>
+            then create an empty php file:
+            </para>
+
+            <para>
+                <screen>
+                <![CDATA[
+            kguest:~/MyProject-packages$ touch empty.php
+                ]]>
+                </screen>
+            </para>
+
+
+            <para>
+            Download and save this package.xml into this new directory; then run pfm.
+            </para>
+
+            <para>
+                <screen>
+                <![CDATA[
+            kguest:~/MyProject-packages$ wget package.xml
+            kguest:~/MyProject-packages$ pfm
+
+            PEAR Package File Manager Command Line Tool
+
+            Please enter the location of your package [.]*:<press enter>
+
+            Enter the base install directory
+
+                1) /dev/null
+
+            Please choose an option: 1
+
+
+            PEAR Package File Manager Command Line Tool
+
+                1. Package name                 [MyProject_Packages]
+                2. Channel/URI                  [URI: file:///MyProject-packages/package.xml]
+                3. Summary                      [this is a wrapper package for install...]
+                4. Description                  [<none>]
+                5. Maintainers
+                6. Version                      [Release: 0.0.1 API: 0.0.1]
+                7. Stability                    [Release: alpha API: alpha]
+                8. License                      [LGPL]
+                9. Notes                        [<none>]
+            10. Dependencies
+            11. Tasks
+            12. Regenerate contents
+            13. Echo package file to stdout
+            14. Save & Quit
+            15. Quit without saving          (ctrl-c)
+
+            Please choose an option from the menu: 10
+
+
+            Edit Dependencies
+
+                1. Return to main menu
+
+                2. Add new dependency
+                3. Clear all dependencies
+
+                4. Change PHP >= 5.2.1
+                5. Change PEAR Installer >= 1.8.0
+
+                Dependencies:
+
+
+            Please choose an option from the menu: 2
+
+            Dependency type [pkg] (pkg,ext,php,prog,os,sapi,zend)*: pkg
+
+            Dependency name*: PHP_CodeSniffer
+
+            Is the dependency (o)ptional or (r)equired [r] (o,r)*: r
+
+            Package type (c)hannel or (u)ri [c] (c,u)*: c
+
+            Dependency channel [pear.php.net]*:
+
+            Minimum version: 1.2.0RC1
+
+            Maximum version:
+
+
+            Edit Dependencies
+
+                1. Return to main menu
+
+                2. Add new dependency
+                3. Clear all dependencies
+
+                4. Change PHP >= 5.2.1
+                5. Change PEAR Installer >= 1.8.0
+
+                Dependencies:
+
+                Required Package dependency "PHP_CodeSniffer" - pear.php.net
+                ]]>
+                </screen>
+            </para>
+
+            <para>
+            Repeat this as required until all packages that you want to be managed have been added; then return to the main menu, save and quit.
+            Naturally, you should also use pfm to change the name of the project described by package.xml to something of your choosing.
+            </para>
+
+        </section>
+        <section xml:id="guide.users.dependencytracking.generatingpackagexml.editor">
+            <title>Creating package.xml Using Text Editor</title>
+            <para>
+            Download the package.xml file from above. Use this as a template and refer to
+            the <link linkend="guide.developers.package2.tags.xml">tag reference for version 2 of package.xml</link> in the developers section for
+            details of how to add dependencies to the file.
+            </para>
+        </section>
+    </section>
+    <section xml:id="guide.users.dependencytracking.testinstall">
+        <title>Testing that the package works - install it</title>
+        <para>
+        foo bar
+        </para>
+        </section>
+</section>

Modified: pear/peardoc/trunk/manual.xml
===================================================================
--- pear/peardoc/trunk/manual.xml	2009-08-31 03:51:20 UTC (rev 287909)
+++ pear/peardoc/trunk/manual.xml	2009-08-31 08:12:07 UTC (rev 287910)
@@ -66,6 +66,7 @@
    &guide.users.installationpyrus;
    &guide.users.installation;
    &guide.users.commandline;
+   &guide.users.dependencytracking;
  </book>

  <book xml:id="pyrus">