cvs: peardoc /en/pyrus plugins.xml

cellog		Sun Jun 28 14:47:15 2009 UTC

  Modified files:              
    /peardoc/en/pyrus	plugins.xml 
  Log:
  new summary of how the plugin system works
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/plugins.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/plugins.xml
diff -u peardoc/en/pyrus/plugins.xml:1.2 peardoc/en/pyrus/plugins.xml:1.3
--- peardoc/en/pyrus/plugins.xml:1.2	Sun Jun 28 03:41:24 2009
+++ peardoc/en/pyrus/plugins.xml	Sun Jun 28 14:47:15 2009
@@ -11,6 +11,49 @@
    Commands add new commands to a frontend for Pyrus, file roles and file tasks
    add new features to package.xml.
   </para>
+  <para>
+   Pyrus, by necessity, requires a clear separation between its plugins and
+   its core.  This is because Pyrus is distributed as a phar archive, which
+   cannot be modified without jumping through several hoops.  For this reason,
+   plugins are installed in a special directory whose location is specified by
+   the <link linkend="pyrus.configuration.user.pluginsdir">plugins_dir</link>
+   user configuration variable.
+  </para>
+  <para>
+   Pyrus also makes a clear separation between regular packages and plugin
+   packages.  Plugins must be installed separate from any non-plugin packages using the
+   <link linkend="pyrus.commands.install.plugin"><literal>--plugin</literal></link>
+   option of the <link linkend="pyrus.commands.install">install</link>,
+   <link linkend="pyrus.commands.upgrade">upgrade</link>, and
+   <link linkend="pyrus.commands.uninstall">uninstall</link> command.  Here is
+   an example, installing the developer tools plugin:
+  </para>
+  <screen>php pyrus.phar install -p PEAR2_Pyrus_Developer</screen>
+  <para>
+   Pyrus defines a plugin as any package that contains one of the three
+   file roles that identify a plugin: <literal>customcommand</literal>,
+   <literal>customrole</literal>, or <literal>customtask</literal>.  In addition,
+   a plugin package can only contain one plugin.  This helps users by mapping
+   one package to one plugin so that when they list plugin packages, it clearly
+   shows all of the plugins that are installed.
+  </para>
+  <para>
+   A plugin's definition is handled by an XML file, which must be referenced
+   using one of the three plugin file roles in package.xml.  Here is an
+   example identifying a custom command in package.xml:
+  </para>
+  <para>
+   <programlisting role="xml">
+    <![CDATA[
+...
+  <dir name="/">
+   <dir name="customcommand" baseinstalldir="/">
+    <file role="customcommand" name="commands.xml"/>
+   </dir>
+...
+    ]]>
+   </programlisting>
+  </para>
 
   &pyrus.plugins.command;
   &pyrus.plugins.role;