cvs: peardoc /en/pyrus/differences frompear.xml

cellog		Thu Jun 18 21:16:26 2009 UTC

  Modified files:              
    /peardoc/en/pyrus/differences	frompear.xml 
  Log:
  add info on difference between PEAR and Pyrus configurations
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/differences/frompear.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/differences/frompear.xml
diff -u peardoc/en/pyrus/differences/frompear.xml:1.2 peardoc/en/pyrus/differences/frompear.xml:1.3
--- peardoc/en/pyrus/differences/frompear.xml:1.2	Thu Jun 18 19:09:35 2009
+++ peardoc/en/pyrus/differences/frompear.xml	Thu Jun 18 21:16:26 2009
@@ -2,7 +2,6 @@
 <section xmlns="http://docbook.org/ns/docbook" xmlns:phd="http://www.php.net/ns/phd" version="lillet" xml:id="pyrus.differences.frompear">
  <info><title>Pyrus: Improvements from the PEAR Installer</title></info>
 
- <phd:toc phd:element="pyrus.differences.frompear" phd:toc-depth="2"/>
  <section xml:id="pyrus.differences.frompear.overview">
   <info><title>Overview</title></info>
   <para>
@@ -107,7 +106,104 @@
  <section xml:id="pyrus.differences.frompear.configuration">
   <info><title>Configuration files</title></info>
   <para>
-   work in progress.
+   One of the most important conceptual changes in Pyrus is how configuration
+   is handled.  PEAR was designed to handle at most 2 installations by default,
+   a system and a user PEAR installation, and it excels at this.  As soon as
+   PEAR is used on multiple installations, a separate configuration file must
+   be specified (as in <literal>pear -c /path/to/another/pear.conf install
+   blah</literal>).  This leads to what is colloquially referred to as
+   <quote>config hell</quote>, where it is easy to accidentally install
+   things into the wrong place without realizing it.  Pyrus's configuration
+   handling is specifically engineered to eliminate config hell, and to make
+   handling multiple PEAR installations simple.
+  </para>
+  <para>
+   PEAR stores all configuration values in a single configuration file, and allows
+   specifying a different configuration file for different setups.  In addition,
+   PEAR supports automatic cascade of a system configuration file and a user
+   configuration file.  The configuration values are used when installing applications,
+   and for customizing things like the path to php in the PEAR Installer's
+   <literal>pear</literal> command.  Configuration files are stored separate
+   from the PEAR installations that they represent.
+  </para>
+  <para>
+   Pyrus instead splits up configuration files into two separate components: one
+   file contains user customizations such as the preferred stability of packages
+   to install, the username and password for logging into a channel, the verbose
+   setting and so on.  Configuration variables that affect where to install files
+   are stored in a separate configuration that is tightly bound to the PEAR
+   installation.
+  </para>
+  <para>
+   Thus, a PEAR configuration setup might look like:
+  </para>
+  <para>
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      System configuration in <literal>/etc/pear.conf</literal>, defines
+      <literal>php_dir</literal> as <literal>/usr/local/lib/php</literal>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      User configuration in <literal>/home/username/.pearrc</literal>, defines
+      <literal>php_dir</literal> as <literal>/home/username/pear</literal>.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>include_path</literal> is set to <literal>/home/username/pear:/usr/local/lib/php</literal>.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   The equivalent configuration setup with Pyrus would look like:
+  </para>
+  <para>
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      Pyrus-based installation in <literal>/usr/local/lib/pear</literal>, system configuration
+      stored in <literal>/usr/local/pear/.config</literal> and php files in
+      <literal>/usr/local/lib/pear/php</literal>.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      Another Pyrus-based installation in <literal>/home/username/pear</literal>, system
+      configuration stored in <literal>/home/username/pear/.config</literal> and php
+      files in <literal>/home/username/pear/php</literal>.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      User configuration in <literal>/home/username/.pear/pearconfig.xml</literal>.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>include_path</literal> is set to <literal>/home/username/pear:/usr/local/lib/pear/php</literal>.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+  </para>
+  <para>
+   By default, Pyrus uses the <literal>include_path</literal> to locate PEAR
+   installations, but this is configurable with the new user configuration
+   variable <literal>my_pear_path</literal>, which is a <constant>PATH_SEPARATOR</constant>
+   separated list of paths to PEAR installations.
+  </para>
+  <para>
+   In addition, an explicit path can be directly passed to Pyrus:
+  </para>
+  <para>
+   <literal>php pyrus.phar /home/username/pear:/usr/local/lib/pear list-packages</literal>
+  </para>
+  <para>
+   The above command will list the installed packages in both registries in
+   <literal>/home/username/pear</literal> and in <literal>/usr/local/lib/pear/php</literal>.
   </para>
  </section>
  <section xml:id="pyrus.differences.frompear.registry">
@@ -122,4 +218,10 @@
    work in progress.
   </para>
  </section>
+ <section xml:id="pyrus.differences.frompear.pecl">
+  <info><title>Installing and Building PECL extensions</title></info>
+  <para>
+   work in progress.
+  </para>
+ </section>
 </section>