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

cellog		Thu Jun 18 22:12:49 2009 UTC

  Modified files:              
    /peardoc/en/pyrus/differences	frompear.xml 
  Log:
  new docs on differences between pyrus plugins and PEAR plugins
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/differences/frompear.xml?r1=1.4&r2=1.5&diff_format=u
Index: peardoc/en/pyrus/differences/frompear.xml
diff -u peardoc/en/pyrus/differences/frompear.xml:1.4 peardoc/en/pyrus/differences/frompear.xml:1.5
--- peardoc/en/pyrus/differences/frompear.xml:1.4	Thu Jun 18 21:43:16 2009
+++ peardoc/en/pyrus/differences/frompear.xml	Thu Jun 18 22:12:48 2009
@@ -258,7 +258,52 @@
  <section xml:id="pyrus.differences.frompear.plugins">
   <info><title>Extending Pyrus: plugins</title></info>
   <para>
-   work in progress.
+   The PEAR Installer allowed packages to install custom commands as well as
+   custom file roles and custom file tasks that are used in package.xml.  Pyrus
+   also allows this, but the format of plugins is very different.  If you are
+   simply a user of PEAR, you probably won't notice the difference, except that
+   some packages that use custom file roles or tasks will not be installable by
+   Pyrus until the maintainer releases an update that will work with both PEAR
+   and Pyrus.
+  </para>
+  <para>
+   PEAR extensions are installed directly into the location where the PEAR
+   installer is located.  Thus, if PEAR is located in
+   <literal>/usr/local/lib/php/PEAR</literal>, a custom command must install
+   its XML information file and PHP script into
+   <literal>/usr/local/lib/php/PEAR/Command</literal>,
+   a custom file role must install its XML information file and PHP script into
+   <literal>/usr/local/lib/php/PEAR/Installer/Role</literal> and a custom file
+   task must install its PHP script into
+   <literal>/usr/local/lib/php/PEAR/Task</literal>.
+  </para>
+  <para>
+   Pyrus is distributed as a phar archive, so this model is no longer physically
+   possible, one cannot just magically insert files into the phar archive without
+   considerable pain and annoyance (the phar.readonly INI setting must be disabled
+   by hand).  Instead, Pyrus installs all plugins into a location specified
+   by the new <literal>plugins_dir</literal> user configuration variable.
+   By default, this installs plugins into <literal>$HOME/.pear/plugins</literal>
+   on unix systems, and <literal>My Documents\pear\plugins</literal> on Windows.
+  </para>
+  <para>
+   All plugins to Pyrus now must provide an xml file with one of the three
+   new file roles <literal>customcommand</literal>, <literal>customrole</literal>
+   or <literal>customtask</literal> in package.xml.  Pyrus uses the information
+   in the XML file to locate the PHP script that will execute the plugin.  In
+   addition, only one plugin is allowed per package, and the first one Pyrus
+   encounters is the one that will be used.  More information on custom plugins
+   is provided in the <link linkend="pyrus.plugins">Pyrus plugins</link> section
+   of the manual.
+  </para>
+  <para>
+   For developers of existing PEAR custom roles/tasks and post-install scripts,
+   a special kind of file role that allows configuration of your package after
+   installation, making your work compatible with Pyrus can be accomplished.
+   See the documentation
+   on <link linkend="pyrus.differences.customroles">Custom Roles</link>,
+   <link linkend="pyrus.differences.customtasks">Custom Tasks</link>, and
+   <link linkend="pyrus.differences.postinstallscripts">Post-install scripts</link>.
   </para>
  </section>
  <section xml:id="pyrus.differences.frompear.pecl">