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

cellog		Thu Jun 25 15:02:20 2009 UTC

  Modified files:              
    /peardoc/en/pyrus/differences	frompear.xml 
  Log:
  new docs on differences between pyrus and PEAR for building PECL packages
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/differences/frompear.xml?r1=1.6&r2=1.7&diff_format=u
Index: peardoc/en/pyrus/differences/frompear.xml
diff -u peardoc/en/pyrus/differences/frompear.xml:1.6 peardoc/en/pyrus/differences/frompear.xml:1.7
--- peardoc/en/pyrus/differences/frompear.xml:1.6	Wed Jun 24 14:04:29 2009
+++ peardoc/en/pyrus/differences/frompear.xml	Thu Jun 25 15:02:20 2009
@@ -323,7 +323,73 @@
  <section xml:id="pyrus.differences.frompear.pecl">
   <info><title>Installing and Building PECL extensions</title></info>
   <para>
-   work in progress.
+   PEAR's handling of PECL extensions has been somewhat dodgy, with reports of
+   issues with phpize failing, and other problems.
+   Pyrus attempts to fix this through two major changes to the way PECL packages
+   are built and installed.
   </para>
+  <para>
+   <orderedlist>
+    <listitem>
+     <simpara>
+      PECL packages are installed into a new location <literal>src/</literal>
+      and then built directly inside this location.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      The same tool process used to build extensions by hand is used verbatim
+      by pyrus to build the extension
+     </simpara>
+    </listitem>
+   </orderedlist>
+  </para>
+  <section>
+   <title>PECL installation changes</title>
+   <para>
+    PEAR builds PECL packages by creating a temporary directory, installing all of
+    the source files into this directory, building the extension, harvesting
+    built files, and finally removes the temporary directory.  This system works
+    most of the time, but if there is a problem, it is impossible to debug because
+    the sources are removed.
+   </para>
+   <para>
+    Pyrus solves this by splitting PECL package installation into two components,
+    installation and build.  The installation process simply places the
+    source files into a sub-directory of the <literal>src_dir</literal> configuration
+    variable, and thus makes it possible to debug problems or even apply patches
+    to the source and re-build.
+   </para>
+  </section>
+  <section>
+   <title>PECL build</title>
+   <para>
+    The new <literal>build</literal> command enhances PEAR's package building by
+    directly calling this sequence:
+   </para>
+   <para>
+    <screen>
+     <![CDATA[
+phpize --clean
+phpize
+./configure [any options specified by <configureoptions>]
+make
+make install
+     ]]>
+    </screen>
+   </para>
+   <para>
+    This is the same sequence one would use to build a PECL extension by hand.
+    In addition, <function>proc_open</function> is used instead of
+    <function>popen</function>, which allows better monitoring and control of
+    the processes in question.
+   </para>
+   <para>
+    Lastly, Pyrus is more cross-platform than PEAR, as it replaces a
+    call to <literal>find</literal> and <literal>xargs</literal> with native
+    PHP iteration over the modules directory when listing extension components
+    that were built.
+   </para>
+  </section>
  </section>
 </section>