Using tasks to customize file installation
Tasks provide a flexible and customizable way to manipulate file contents or to perform
complex installation tasks (hence the name "tasks"). By default, PEAR comes
with 4 tasks, but customized tasks can be added simply by adding a file into the
PEAR/Tasks directory that follows the conventions of existing tasks. This page does
not describe how to create a custom task, only how to use them in package.xml.
There are 3 basic tasks and 1 complex task distributed with PEAR. The basic tasks are
"tasks:replace", "tasks:windowseol", and "tasks:unixeol". The complex task
is "tasks:postinstallscript". "tasks:replace" is nearly identical to the old
<replace> tag from package.xml 1.0, and does a text search-and-replace of a file's
contents. "tasks:windowseol" and "tasks:unixeol" manipulate the line endings of
a file to ensure that the correct line endings are in place for critical files like DOS
.bat batch files and unix shell scripts. "tasks:postinstallscript" allows users to
choose to run a script to perform further installation functions.
<tasks:replace> - customizing file contents
The replace task has 3 required attributes:
type - This must be either package-info or pear-config. package-info
replacements extract information from package.xml itself to use as the replacement text.
pear-config replacements use the value of a configuration variable (as displayed by
) as the text for replacement.
from - Text to search for in a file. Traditionally, this text
is enclosed in "@" to differentiate it from normal text, as in from="@version@"
to - Abstract item to use as a replacement for all occurences of
"from". package-version replacements can be one of version, release_date,
release_state, release_license, release_notes, apiversion, name, summary, description,
notes, time, date, and for some packages extends, srcpackage, srcuri, and providesextension.
Note that package-info replacements are performed at packaging time, so files contain
package-info replacements inside a .tgz/.tar release. pear-config replacements can only
occur on the installation system, and are performed at install-time.
<tasks:windowseol> - converting line endings to \r\n
This task can be used to enable packaging of windows-specific files (like DOS batch files)
on a non-windows system, such as unix systems that convert line endings to \n. Note that this task
is performed at package-time, as well as at install-time, so files will contain the correct line
endings inside a .tgz/.tar release.
<tasks:unixeol> - converting line endings to \n
This task can be used to enable packaging of unix-specific files (like sh shell scripts)
on a non-unix system, such as windows systems that convert line endings to \r\n. Note that this task
is performed at package-time, as well as at install-time, so files will contain the correct line
endings inside a .tgz/.tar release.
<tasks:postinstallscript> - extreme customization
The postinstallscript task informs the installer that the file it references is a post-installation
script.
For security reasons, post-install scripts must be manually executed by the users, and as such
the installer has special code that is separate from other tasks.
The <postinstallscript> tag may define parameters that are used by the installer to
retrieve user input. In order to support both the web installer and the command-line installer,
all processing of input is performed by PEAR and passed to the post-install script in a
strict format. All you need to do is define the parameters using xml inside the
<postinstallscript> tag.
Here is the xml representing a simple post-install script with parameters:
<tasks:postinstallscript>
<tasks:paramgroup>
<tasks:id>first</tasks:id>
<tasks:param>
<tasks:name>test</tasks:name>
<tasks:prompt>Testing Thingy</tasks:prompt>
<tasks:type>string</tasks:type>
</tasks:param>
</tasks:paramgroup>
</tasks:postinstallscript> |
Note that the only type recognized at this stage is "string" but others will follow.
A more complex example follows:
<tasks:postinstallscript>
<tasks:paramgroup>
<tasks:id>first</tasks:id>
<tasks:instructions>The first group of questions relates
primarily to your favorite color. Answer wisely.
</tasks:instructions>
<tasks:param>
<tasks:name>test</tasks:name>
<tasks:prompt>Testing Thingy</tasks:prompt>
<tasks:type>string</tasks:type>
<tasks:default>hi</tasks:default>
</tasks:param>
<tasks:param>
<tasks:name>test2</tasks:name>
<tasks:prompt>Testing Thingy 2</tasks:prompt>
<tasks:type>string</tasks:type>
</tasks:param>
</tasks:paramgroup>
<tasks:paramgroup>
<tasks:id>second</tasks:id>
<tasks:name>first::test</tasks:name>
<tasks:conditiontype>preg_match</tasks:conditiontype>
<tasks:value>g+</tasks:value>
<tasks:param>
<tasks:name>test</tasks:name>
<tasks:prompt>Testing Thingy a</tasks:prompt>
<tasks:type>string</tasks:type>
<tasks:default>hi</tasks:default>
</tasks:param>
<tasks:param>
<tasks:name>test2</tasks:name>
<tasks:prompt>Testing Thingy b</tasks:prompt>
<tasks:type>string</tasks:type>
</tasks:param>
</tasks:paramgroup>
</tasks:postinstallscript> |
This post-installation script has two parameter groups. The first parameter group
has special instructions that are displayed to the user to assist in answering the
required prompts. After the first group is processed,
the second group is processed (naturally). However, in this case, the second group is a
conditional parameter group. A conditional parameter group examines the user input from
previous parameter groups and only displays its parameter prompts if a single parameter
fits a test. The condition is defined by three tags, <tasks:name>, <tasks:conditiontype>,
and <tasks:value>. Note that all three tags are required or xml validation will fail.
<tasks:name> is the parameter name from a previous parameter group. The format of name is
groupID::parameterName, so as you see above, "first::test" refers to the
<tasks:param> first from the <tasks:paramgroup> test.
<tasks:conditiontype> determines how the parameter input function will process the value of
the parameter specified in <tasks:name>, and can be one of three values, "=" "!="
or "preg_match".
=: This (obviously) tests whether the parameters value is equal to the <tasks:value> tag
!=: This (obviously) tests whether the parameters value is not equal to the <tasks:value> tag
preg_match: This uses the content of the <tasks:value> tag as if it were the stuff between
/ and / in a preg_match()
function call. Do NOT include // brackets in
the regular expression. In the <tasks:paramgroup> second, the value "g+" will become:
<?php
preg_match('/g+/', first::test value)
?> |
