tasks for <file>s

tasks for <file>s -- specialized file installation and manipulation

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:

  1. 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
    pear config-show
    ) as the text for replacement.

  2. from - Text to search for in a file. Traditionally, this text is enclosed in "@" to differentiate it from normal text, as in from="@version@"

  3. to - Abstract item to use as a replacement for all occurences of "from". package-info 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> test from the <tasks:paramgroup> first.

<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".