[prev in list] [next in list] [prev in thread] [next in thread]
List: pear-doc
Subject: [PEAR-DOC] cvs: peardoc /en language-defs.ent /en/guide/users concepts.xml /en/guide/users/concept
From: "Greg Beaver" <cellog () php ! net>
Date: 2009-07-01 19:12:43
Message-ID: cvscellog1246475563 () cvsserver
[Download RAW message or body]
cellog Wed Jul 1 19:12:43 2009 UTC
Added files:
/peardoc/en/guide/users/concepts filerole.xml filetasks.xml
Modified files:
/peardoc/en language-defs.ent
/peardoc/en/guide/users concepts.xml
/peardoc/en/pyrus/differences customroles.xml
/peardoc/en/pyrus/plugins role.xml task.xml
Log:
finish docs on pyrus plugins
["cellog-20090701191243.txt" (text/plain)]
http://cvs.php.net/viewvc.cgi/peardoc/en/language-defs.ent?r1=1.13&r2=1.14&diff_format=u
Index: peardoc/en/language-defs.ent
diff -u peardoc/en/language-defs.ent:1.13 peardoc/en/language-defs.ent:1.14
--- peardoc/en/language-defs.ent:1.13 Sat Jun 27 05:18:05 2009
+++ peardoc/en/language-defs.ent Wed Jul 1 19:12:43 2009
@@ -1,4 +1,4 @@
-<!-- $Revision: 1.13 $ -->
+<!-- $Revision: 1.14 $ -->
<!ENTITY PEARManual "PEAR Manual">
<!ENTITY Translatedby "Translated by">
@@ -10,7 +10,7 @@
<!ENTITY Channels "Channels: distributing your packages">
<!ENTITY UsersGuide "User Guide">
<!ENTITY NewMaintainersGuide "Becoming a PEAR developer: how to get involved">
-<!ENTITY ChangesInPear14 "PEAR Installer: customizing packages">
+<!ENTITY ChangesInPear14 "PEAR Installer: customizing the installer itself">
<!ENTITY Features "Features">
<!ENTITY PEAR "PEAR: the PHP Extension and Application Repository">
<!ENTITY PEAR2Packages "PEAR2 Packages">
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/guide/users/concepts.xml
diff -u peardoc/en/guide/users/concepts.xml:1.1 \
peardoc/en/guide/users/concepts.xml:1.2
--- peardoc/en/guide/users/concepts.xml:1.1 Sat Jun 27 05:18:06 2009
+++ peardoc/en/guide/users/concepts.xml Wed Jul 1 19:12:43 2009
@@ -17,4 +17,6 @@
&guide.users.concepts.version;
&guide.users.concepts.abstractpackage;
&guide.users.concepts.channel;
+ &guide.users.concepts.filerole;
+ &guide.users.concepts.filetasks;
</chapter>
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/differences/customroles.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/differences/customroles.xml
diff -u peardoc/en/pyrus/differences/customroles.xml:1.2 \
peardoc/en/pyrus/differences/customroles.xml:1.3
--- peardoc/en/pyrus/differences/customroles.xml:1.2 Fri Jun 26 03:25:48 2009
+++ peardoc/en/pyrus/differences/customroles.xml Wed Jul 1 19:12:43 2009
@@ -50,7 +50,7 @@
<![CDATA[
<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
<name>php</name>
- <classprefix>PEAR2_Pyrus_Installer_Role</classprefix>
+ <class>PEAR2_Pyrus_Installer_Role_Php</class>
<releasetypes>php</releasetypes>
<releasetypes>extsrc</releasetypes>
<releasetypes>extbin</releasetypes>
@@ -60,9 +60,7 @@
<locationconfig>php_dir</locationconfig>
<honorsbaseinstall>1</honorsbaseinstall>
<unusualbaseinstall />
- <phpfile>1</phpfile>
<executable />
- <phpextension />
</role>
]]>
</programlisting>
@@ -70,10 +68,12 @@
<para>
The most obvious difference is that Pyrus now includes the name of the role,
PEAR extracts the role name from the name of the file (which in the
- example above was <literal>Php.xml</literal>).
+ example above was <literal>Php.xml</literal>). In addition, the
+ <literal><phpfile></literal> and <literal><phpextension></literal>
+ elements have been removed.
</para>
<para>
- The details of new tags like <classprefix> and <autoloadpath> are
+ The details of new tags like <class> and <autoloadpath> are
documented in the full documentation of custom roles
<link linkend="pyrus.plugins.role">here</link>.
</para>
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/plugins/role.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/plugins/role.xml
diff -u peardoc/en/pyrus/plugins/role.xml:1.1 peardoc/en/pyrus/plugins/role.xml:1.2
--- peardoc/en/pyrus/plugins/role.xml:1.1 Thu Jun 18 04:50:40 2009
+++ peardoc/en/pyrus/plugins/role.xml Wed Jul 1 19:12:43 2009
@@ -1,9 +1,184 @@
<?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" \
xml:id="pyrus.plugins.role"> +<section xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet" + \
xml:id="pyrus.plugins.role"> <info><title>Pyrus plugins: custom file \
roles</title></info>
<section xml:id="pyrus.plugins.role.intro">
<info><title>Introduction</title></info>
- <para>This is a work in progress.</para>
+ <para>
+ If you are not familiar with how file roles install, read the
+ <link linkend="guide.users.concepts.filerole">introduction to file roles</link>
+ first. This segment of the documentation assumes you are familiar with
+ concepts such as <literal>baseinstalldir</literal> and with what a file
+ role means in terms of installation location.
+ </para>
+ <para>
+ Custom file roles can implement a single role, and are defined by
+ an xml file that is noted in package.xml with the <literal>customrole</literal>
+ file role. The XML format is defined and validated by pyrus with the
+ <link xlink:href="http://svn.pear.php.net/PEAR2/Pyrus/trunk/data/customrole-2.0.xsd">customrole-2.0.xsd</link>
+ XSchema file.
+ </para>
+ <para>
+ Here is a human-readable custom file role xml file definition.
+ Optional elements are enclosed in [brackets], and if there is a choice of
+ values, they are delimited with a vertical bar <literal>|</literal> and
+ enclosed in (parentheses).
+ </para>
+ <programlisting role="xml">
+ <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<role version="2.0" xmlns="http://pear2.php.net/dtd/customrole-2.0">
+ <name>rolename</name>
+ <class>MyPlugin_Rolename</class>
+[<validationmethod>validate</validationmethod>]
+[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
+(<releasetype>php</releasetype>|<releasetype>extsrc</releasetype>|
+ <releasetype>extbin</releasetype>|<releasetype>zendextsrc</releasetype>|
+ <releasetype>zendextbin</releasetype>)
+ <installable>(1|0)</installable>
+ <locationconfig>config_var</locationconfig>
+ <honorsbaseinstall>(1|0)</honorsbaseinstall>
+ <unusualbaseinstall>(1|0)</unusualbaseinstall>
+ <executable>(1|0)</executable>
+[<configvar>
+ <name>config_name</name>
+ <type>string</type>
+ <default>
+ <![CDATA[
+ <?php $default = 'hi'; ?>
+ ]]]]><![CDATA[>
+ </default>
+ <doc>Extensive, multi-line documentation</doc>
+ [<validset>val1</validset><validset>val2</validset>...]
+ <prompt>summary documentation</prompt>
+ <group>Custom</group>
+ <configtype>(system|user|channel-specific)</configtype>
+ </configvar>]*
+</role>
+ ]]>
+ </programlisting>
+ </section>
+ <section xml:id="pyrus.plugins.role.autoload">
+ <title>Telling Pyrus how to load your role: <class> and \
<autoloadpath></title> + <para>
+ This is the same method used for all plugins, and is documented
+ <link linkend="pyrus.plugins.autoload">here</link>.
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.packagetimevalidation">
+ <title>Validating your custom role at packaging time</title>
+ <para>
+ Some roles benefit from the ability to validate the files they represent
+ at packaging time. For instance, a <literal>customcommand</literal> file
+ is checked to ensure it conforms to its XML schema, so that a custom command
+ with invalid XML cannot be distributed by mistake.
+ </para>
+ <para>
+ By convention, a validation method should be named <literal>validate</literal>,
+ although the xml supports any name. The method name should be placed in
+ the <literal><validationmethod</literal> tag, and the method itself should
+ have the same method signature as this example from Pyrus's
+ <literal>customrole</literal> validation:
+ </para>
+ <programlisting role="php">
+ <![CDATA[
+ function validate(PEAR2_Pyrus_IPackage $package, array $file)
+ {
+ $parser = new PEAR2_Pyrus_XMLParser;
+ $schemapath = PEAR2_Pyrus::getDataPath();
+ if (!file_exists(PEAR2_Pyrus::getDataPath() . '/customrole-2.0.xsd')) {
+ $schemapath = realpath(__DIR__ . '/../../../../data');
+ }
+ $taskschema = $schemapath . '/customrole-2.0.xsd';
+ try {
+ $taskinfo = \
$parser->parse($package->getFilePath($file['attribs']['name']), $taskschema); + \
} catch (\Exception $e) { + throw new \
PEAR2_Pyrus_Installer_Role_Exception('Invalid custom role definition file,' . + \
' file does not conform to the schema', $e); + }
+ }
+ ]]>
+ </programlisting>
+ <para>
+ A custom file role package-time validator should throw a
+ <literal>PEAR2_Pyrus_Installer_Role_Exception</literal> exception object
+ with an error message describing the reason for validation failure, or simply
+ return on success.
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.releasetype">
+ <title>Release Types and file roles</title>
+ <para>
+ The <literal><releasetype></literal> element is used to tell Pyrus
+ which releases can contain a file with this role. For instance, the
+ <literal>src</literal> role only has meaning in a PHP extension source release,
+ and is only allowed in <literal>extsrc</literal> and \
<literal>zendextsrc</literal> + release types.
+ </para>
+ <para>
+ There are 5 release types that Pyrus recognizes:
+ <itemizedlist>
+ <listitem><para><literal>php</literal> - this is for PEAR-style packages \
distributing PHP code</para></listitem> + \
<listitem><para><literal>extsrc</literal> - this is for PHP extension source \
packages</para></listitem> + <listitem><para><literal>extbin</literal> - this is \
for PHP extension binary packages</para></listitem> + \
<listitem><para><literal>zendextsrc</literal> - this is for PHP Zend extension source \
packages</para></listitem> + <listitem><para><literal>zendextbin</literal> - this \
is for PHP Zend extension binary packages</para></listitem> + </itemizedlist>
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.installable">
+ <title><installable></title>
+ <para>
+ If set to <literal>0</literal>, the file will not actually be installed onto
+ the system. Most file roles should set this to <literal>1</literal>.
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.locationconfig">
+ <title><locationconfig></title>
+ <para>
+ This element is used to tell Pyrus which configuration variable should be
+ used to determine where to install the file. This can be a
+ <link linkend="pyrus.plugins.role.configvar">custom configuration \
variable</link>. + </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.baseinstall">
+ <title><honorsbaseinstall> and <unusualbaseinstall></title>
+ <para>
+ The <literal><honorsbaseinstall></literal> element tells Pyrus to
+ honor the <literal>baseinstalldir</literal> attribute (documentation on
+ baseinstalldir is <link \
linkend="guide.users.concepts.filerole.baseinstalldir">here</link>) + for roles \
like <literal>php</literal>. + </para>
+ <para>
+ The <literal><unusualbaseinstall></literal> element tells Pyrus to
+ honor the <literal>baseinstalldir</literal> attribute for roles like
+ <literal>data</literal> that also prepend channel/package name to the
+ installation location.
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.executable">
+ <title><executable></title>
+ <para>
+ If <literal><executable></literal> is set to <literal>1</literal>,
+ Pyrus will make the installed file an executable file on unix systems
+ (the equivalent of <screen>chmod +x filename</screen>).
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.role.configvar">
+ <title>Defining custom configuration variables</title>
+ <para>
+ A custom file role can optionally define a single or multiple custom
+ configuration variables. There are 3 kinds of configuration variables
+ that Pyrus supports, <literal>system</literal>, <literal>user</literal> and
+ <literal>channel-specific</literal>. Documentation on configuration is
+ available <link linkend="pyrus.configuration">here</link>. Read that before
+ continuing in order to understand how different configuration variables work.
+ </para>
+ <para>
+ Pyrus supports one type of configuration variable: <literal>string</literal>.
+ The values can be restricted to a specific set of values with the
+ <literal><validset></literal> element.
+ </para>
</section>
</section>
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/plugins/task.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/pyrus/plugins/task.xml
diff -u peardoc/en/pyrus/plugins/task.xml:1.1 peardoc/en/pyrus/plugins/task.xml:1.2
--- peardoc/en/pyrus/plugins/task.xml:1.1 Thu Jun 18 04:50:40 2009
+++ peardoc/en/pyrus/plugins/task.xml Wed Jul 1 19:12:43 2009
@@ -1,9 +1,209 @@
<?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" \
xml:id="pyrus.plugins.task"> +<section xmlns="http://docbook.org/ns/docbook" \
xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet" + \
xml:id="pyrus.plugins.task"> <info><title>Pyrus plugins: custom file \
tasks</title></info>
<section xml:id="pyrus.plugins.task.intro">
<info><title>Introduction</title></info>
- <para>This is a work in progress.</para>
+ <para>
+ If you are not familiar with how file tasks work, read the
+ <link linkend="guide.users.concepts.filetasks">introduction to file tasks</link>
+ first.
+ </para>
+ <para>
+ Custom file tasks can implement a single task, and are defined by
+ an xml file that is noted in package.xml with the <literal>customtask</literal>
+ file role. The XML format is defined and validated by pyrus with the
+ <link xlink:href="http://svn.pear.php.net/PEAR2/Pyrus/trunk/data/customtask-2.0.xsd">customtask-2.0.xsd</link>
+ XSchema file.
+ </para>
+ <para>
+ Here is a human-readable custom file task xml file definition.
+ Optional elements are enclosed in [brackets].
+ </para>
+ <programlisting role="xml">
+ <![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<task version="2.0" xmlns="http://pear2.php.net/dtd/customtask-2.0">
+ <name>taskname</name>
+ <class>MyPlugin_Taskname</class>
+[<autoloadpath>relative/path/to/MyPlugin</autoloadpath>]
+</task>
+ ]]>
+ </programlisting>
+ </section>
+ <section xml:id="pyrus.plugins.task.autoload">
+ <title>Telling Pyrus how to load your task: <class> and \
<autoloadpath></title> + <para>
+ This is the same method used for all plugins, and is documented
+ <link linkend="pyrus.plugins.autoload">here</link>.
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.task.taskclass">
+ <title>Defining the task: the task class</title>
+ <para>
+ A custom file task must extend the <literal>PEAR2_Pyrus_Task_Common</literal>
+ class, and must implement a few methods:
+ <itemizedlist>
+ <listitem><simpara><function>validateXml</function></simpara></listitem>
+ <listitem><simpara><function>startSession</function></simpara></listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ Optionally, <function>__construct</function> may be used to do special
+ pre-processing, storing of information or other setup tasks.
+ </para>
+ <para>
+ A task must also define two class constants, <constant>TYPE</constant>
+ and <constant>PHASE</constant>. <constant>TYPE</constant> should be one of
+ <literal>'simple'</literal> or
+ <literal>'script'</literal>. <literal>'script'</literal> tasks are
+ post-install scripts, and are executed by the
+ <link linkend="pyrus.commands.runscripts">run-scripts</link> command.
+ <literal>'simple'</literal> tasks are executed while installation is
+ in progress.
+ </para>
+ <para>
+ <constant>PHASE</constant> should be one of:
+ <itemizedlist>
+ <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::PACKAGE</constant></simpara></listitem>
+ <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::INSTALL</constant></simpara></listitem>
+ <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL</constant></simpara></listitem>
+ <listitem><simpara><constant>PEAR2_Pyrus_Task_Common::POSTINSTALL</constant></simpara></listitem>
+ </itemizedlist>
+ <constant>PEAR2_Pyrus_Task_Common::POSTINSTALL</constant> is only used by
+ post-install scripts, the other 3 are used to determine at what time the
+ task should be called. If your custom task only works at installation-time,
+ use <constant>PEAR2_Pyrus_Task_Common::INSTALL</constant>. If the task can
+ perform only at package time (this is exceedingly rare), use
+ <constant>PEAR2_Pyrus_Task_Common::PACKAGE</constant>. Most tasks should use
+ <constant>PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL</constant>. If your task
+ can perform its task at packaging time, then you should override the
+ <function>isPreProcessed</function> method and return true. Some tasks, such
+ as the <literal>replace</literal> task, perform some of their actions at
+ package time, and the rest at install time. The \
<function>isPreProcessed</function> + method should only return true if the XML of \
the specific task could be + processed at package time.
+ </para>
+ <para>
+ The <function>startSession</function> method is used to actually execute the
+ task, and is passed a read/write file resource that is set to the beginning
+ of the file being installed. The full path of the file's final installation
+ location is also passed in, and can be used for throwing exceptions. All
+ errors should be handled by throwing a \
<literal>PEAR2_Pyrus_Task_Exception</literal> + or one of its descendants.
+ </para>
+ <para>
+ The <function>validateXml</function> method should validate the XML as
+ represented in an array format. The array uses associative arrays for tags,
+ the <literal>attribs</literal> index for attributes, and for a tag with both
+ attributes and content, the <literal>_content</literal> index contains the
+ content. If present, the <literal>tasks:</literal> namespace is removed
+ from the tags prior to passing to <function>validateXml</function>. On
+ encountering validation errors, the method should throw one of the four
+ exceptions in the example below.
+ </para>
+ </section>
+ <section xml:id="pyrus.plugins.task.example">
+ <title>Example Custom Task</title>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+class MyPlugin_Taskname extends PEAR2_Pyrus_Task_Common
+{
+ const TYPE = 'simple';
+ const PHASE = PEAR2_Pyrus_Task_Common::PACKAGEANDINSTALL;
+
+ /**
+ * Initialize a task instance with the parameters
+ * @param array raw, parsed xml
+ * @param array attributes from the <file> tag containing this task
+ * @param string|null last installed version of this package
+ */
+ function __construct($pkg, $phase, $xml, $attribs, $lastversion)
+ {
+ parent::__construct($pkg, $phase, $xml, $attribs, $lastversion);
+ // do any special parsing of attributes/contents here
+ // phase is one of PEAR2_Pyrus_Task_Common::PACKAGE,
+ // PEAR2_Pyrus_Task_Common::INSTALL, or
+ // PEAR2_Pyrus_Task_Common::POSTINSTALL
+ }
+
+ /**
+ * Validate the basic contents of a <taskname> tag
+ * @param PEAR_Pyrus_IPackageFile
+ * @param array
+ * @param array the entire parsed <file> tag
+ * @param string the filename of the package.xml
+ * @throws PEAR2_Pyrus_Task_Exception_InvalidTask
+ * @throws PEAR2_Pyrus_Task_Exception_NoAttributes
+ * @throws PEAR2_Pyrus_Task_Exception_MissingAttribute
+ * @throws PEAR2_Pyrus_Task_Exception_WrongAttributeValue
+ */
+ static function validateXml(PEAR2_Pyrus_IPackage $pkg, $xml, $fileXml, $file)
+ {
+ if (!isset($xml['attribs'])) {
+ throw new PEAR2_Pyrus_Task_Exception_NoAttributes('taskname', $file);
+ }
+ if (!isset($xml['attribs']['attributename'])) {
+ throw new PEAR2_Pyrus_Task_Exception_MissingAttribute('taskname',
+ $attrib, $file);
+ }
+ if ($xml['attribs']['attributename'] != 'hi'
+ && $xml['attribs']['attributename'] != 'bye') {
+ throw new PEAR2_Pyrus_Task_Exception_WrongAttributeValue('taskname',
+ \
'attributename', + \
$xml['attribs']['attributename'], + \
$file, + \
array('hi', 'bye')); + }
+ }
+ if (MyPlugin_Other_Class::somecondition()) {
+ throw new PEAR2_Pyrus_Task_Exception_InvalidTask(
+ 'general validation errors should use this exception');
+ }
+ return true;
+ }
+
+ /**
+ * Perform the taskname task
+ * @param PEAR2_Pyrus_IPackage
+ * @param resource open file pointer, set to the beginning of the file
+ * @param string the eventual final file location (informational only)
+ * @return string|false
+ */
+ function startSession($fp, $dest)
+ {
+ // use PEAR2_Pyrus_Log::log() to send messages to the user
+ PEAR2_Pyrus_Log::log(3, 'doing stuff');
+ PEAR2_Pyrus_Log::log(0, 'doing more important stuff');
+ // operate directly on the file pointer
+ $contents = stream_get_contents($fp);
+ $contents .= 'hi';
+ rewind($fp);
+ ftruncate($fp, 0);
+ fwrite($fp, $contents);
+ return true;
+ }
+
+ /**
+ * This is used to tell the installer to skip a task that has already been
+ * executed.
+ *
+ * For example, package-info replacement tasks are performed at packaging
+ * time, and do not need to be re-applied on installation
+ * @return bool true if task has already been executed on the file at
+ * packaging time
+ */
+ function isPreProcessed()
+ {
+ // do not implement this method unless your task does its processing
+ // at package-time!
+ return true;
+ }
+}
+?>
+ ]]>
+ </programlisting>
</section>
</section>
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts/filerole.xml?view=markup&rev=1.1
Index: peardoc/en/guide/users/concepts/filerole.xml
+++ peardoc/en/guide/users/concepts/filerole.xml
<?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.concepts.filerole"> <info><title>File roles</title></info>
<para>
Pyrus and The PEAR Installer categorize file types by their \
<literal>role</literal>. A file role is equivalent to the web's concept of \
<literal>MIME type</literal>, a concept that allows web browsers to determine how a \
file should be displayed or processed. A file role allows Pyrus and the PEAR \
Installer to determine where a file should be installed, the conditions under which \
the role can be used, and even whether the file should be installed at all. A file \
may only have one role in a package.
</para>
<para>
Generally speaking, each file role has its own installation location. For
example, <literal>php</literal> files (files whose file role is
<literal>php</literal>) are installed into the location specified by the
<literal>php_dir</literal> configuration variable, <literal>data</literal>
files (files whose file role is <literal>data</literal>) are installed into
the location specified by the <literal>data_dir</literal> configuration
variable. Some file roles do not have a direct mapping of role name
to configuration variable, such as Pyrus's <literal>customcommand</literal>
file role. This file role is installed into the location specified by the
<literal>data_dir</literal> configuration variable.
</para>
<para>
File roles also control how package.xml attributes are handled. The
<literal>php</literal> file role installs files into the exact
relative path as specified in package.xml. The <literal>data</literal>
file role always installs files into a subdirectory containing the package name
for PEAR packages, and both the channel and package name for packages designed
to be installed by Pyrus.
</para>
<para>
Here is an example of the same file path in package.mxl as <literal>php</literal>
role and as <literal>data</literal> role. All examples assume this is a
package named <literal>PackageName</literal> in the \
<literal>pear2.php.net</literal> channel.
</para>
<programlisting role="xml">
<![CDATA[
<contents>
<dir name="\">
<dir name="base">
<file name="foo" role="php">
</dir>
</dir>
</contents>
]]>
</programlisting>
<para>
This installs as <literal>base/foo</literal> in the location specified
by <literal>php_dir</literal>.
</para>
<programlisting role="xml">
<![CDATA[
<contents>
<dir name="\">
<dir name="base">
<file name="foo" role="data">
</dir>
</dir>
</contents>
]]>
</programlisting>
<para>
For PEAR Installer packages, this installs as \
<literal>PackageName/base/foo</literal> in the location specified by \
<literal>php_dir</literal>. For Pyrus packages, this installs as \
<literal>pear2.php.net/PackageName/base/foo</literal>. </para>
<section xml:id="guide.users.concepts.filerole.baseinstalldir">
<title>How the baseinstalldir attribute is handled by different file roles</title>
<para>
The <literal>baseinstalldir</literal> (base installation directory) attribute
is a tool that can be used to install a file into a different directory than
its location in the source repository.
</para>
<para>
As an example, the path in the subversion repository to the file
<literal>PEAR2\Foo.php</literal> is at
<literal>Foo.php</literal>. To inform the installer to install this
package into the <literal>PEAR2</literal> directory, we would use a baseinstalldir
attribute:
</para>
<programlisting role="xml">
<![CDATA[
<contents>
<dir name="\">
<file name="Foo.php" role="php" baseinstalldir="PEAR2">
</dir>
</contents>
]]>
</programlisting>
<para>
The attribute can also be used on <literal><dir></literal> tags to apply
the base installation directory to all files within the directory:
</para>
<programlisting role="xml">
<![CDATA[
<contents>
<dir name="\" baseinstalldir="PEAR2">
<file name="Foo.php" role="php">
</dir>
</contents>
]]>
</programlisting>
<para>
The <literal>baseinstalldir</literal> role can also be used to inform
the PEAR Installer or Pyrus to strip all relative paths by using
<literal>/</literal> as the base installation directory. Here is an
example from the PEAR package:
</para>
<programlisting role="xml">
<![CDATA[
<dir name="scripts" baseinstalldir="/">
<file name="pear.bat" role="script"/>
]]>
</programlisting>
<para>
This file would be installed as <literal>scripts/pear.bat</literal>, but
the <literal>baseinstalldir</literal> attribute of <literal>/</literal>
informs the installer to instead install it to <literal>pear.bat</literal>.
</para>
<para>
Each file role reacts differently to the <literal>baseinstalldir</literal>
attribute. Packages designed to be installed by the PEAR Installer also
handle them differently from packages designed for installation by Pyrus.
The <literal>php</literal>, <literal>script</literal> and <literal>www</literal>
file roles react the
same way as documented above. In packages designed for the PEAR Installer,
the other file roles do not honor the
<literal>baseinstalldir</literal> attribute, meaning they ignore it. For
example:
</para>
<programlisting role="xml">
<![CDATA[
<contents>
<dir name="\" baseinstalldir="PEAR2">
<file name="Foo.dat" role="data">
</dir>
</contents>
]]>
</programlisting>
<para>
installs <literal>Foo.dat</literal> into the \
<literal>PackageName/Foo.dat</literal> directory. The same XML in a package \
designed for installation by Pyrus will install the file into \
<literal>pear2.php.net/PackageName/PEAR2/Foo.dat</literal>. </para>
</section>
</section>
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts/filetasks.xml?view=markup&rev=1.1
Index: peardoc/en/guide/users/concepts/filetasks.xml
+++ peardoc/en/guide/users/concepts/filetasks.xml
<?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.concepts.filetasks"> <info><title>File tasks</title></info>
<para>
Pyrus allows special handling of files through tasks. File tasks can perform
any action necessary both when installing a package and when creating a
package. Both Pyrus and the PEAR Installer ship with 4 built-in tasks,
<literal>replace</literal>, <literal>windowseol</literal>,
<literal>unixeol</literal>, and <literal>postinstallscript</literal>.
</para>
<para>
The built-in tasks are documented <link \
linkend="guide.developers.package2.tasks">here</link>. The documentation also \
describes how to create custom tasks for the PEAR Installer. Custom tasks for Pyrus \
are documented <link linkend="pyrus.plugins.task">here</link>.
</para>
<para>
Tasks are specifically designed to allow customization of an installation, and
particularly modification of a specific file's contents. The
<literal>unixeol</literal> task, for instance, transforms line endings to
UNIX <literal>\n</literal> and is useful for shell scripts that must have
the proper line endings. The <literal>replace</literal> task can be used
to update the version of a package directly in the source code, or to
automatically set up the path to a PEAR Installation in a shell script.
</para>
<para>
Tasks are defined using the XML namespace
<literal>http://pear.php.net/dtd/tasks-1.0</literal>. Most often, this
is declared using <literal>tasks</literal> as the namespace prefix, as in
<literal><![CDATA[xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"]]></literal>.
More than one task can be used for a single file, as shown by this example from
the PEAR package:
</para>
<programlisting role="xml">
<![CDATA[
<file name="pearcmd.php" role="php">
<tasks:replace from="@php_bin@" to="php_bin" type="pear-config" />
<tasks:replace from="@php_dir@" to="php_dir" type="pear-config" />
<tasks:replace from="@pear_version@" to="version" type="package-info" />
<tasks:replace from="@include_path@" to="php_dir" type="pear-config" />
</file>
]]>
</programlisting>
</section>
--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic