# Apache UIMA PEAR Packaging Ant Task Documentation

## Overview

To make UIMA analysis components easily consumable for other users, UIMA defines the PEAR (Processing Engine ARchive) file format. This allows applications and tools to manage UIMA analysis components automatically for verification, deployment, invocation and testing. So far the PEAR file format is the desired output format for an UIMA analysis component. With the PEAR packaging Ant Task it is possible to create such a PEAR package for the analysis component automatically.

## Using The PEAR Packaging Ant Task

To use the PEAR packaging Ant task it is necessary to define an additional classpath setting for the ant build. The two necessary jars for this setting are the `uima-core.jar` that contains the PEAR packaging code and the `uima-pear-ant-task.jar` that contains the code for the PEAR packaging Ant task. The additional classpath setting can look like:

    <path id="pearTask.classpath">
      <fileset dir="/home/apache-uima/lib/" includes="uima-pear-ant-task.jar"/>
      <fileset dir="/home/apache-uima/lib/" includes="uima-core.jar"/>
    </path>

Update the classpath fileset with your local path settings.

Next we have to define a custom Ant task for the PEAR packaging. The definition looks like:

    <taskdef
       name="packagePear"
       classname="org.apache.uima.pear.tools.PearPackagingAntTask"
       classpathref="pearTask.classpath"/>

The custom PEAR packaging Ant task is called `packagePear`. This task name is used later to package a PEAR file. The `classname` attribute contains the main class of the PEAR packaging Ant task component and should not be changed. The `classpathref` attribute refers the defined `pearTask.classpath` that is necessary to execute the PEAR packaging task.

Now we are ready to use the PEAR packaging Ant task within our build target. To call the PEAR packaging just integrate the custom defined task `<packagePear>`as shown in the fragment below:

    <packagePear
       componentID="SampleAnnotator"
       mainComponentDesc="desc/mainComponentDesc.xml"
       classpath="$main_root/pearClasspahtEntry;$main_root/anotherPearClasspahtEntry"
       datapath="$main_root/resources"
       mainComponentDir="/home/user/workspace/SampeAnntotator"
       targetDir="/home/user/pearArchive">
       <envVar name="ENV_VAR_NO1" value="value1"/>
       <envVar name="ENV_VAR_NO2" value="value2"/>
    </packagePear>

The `<packagePear>` task has the following mandatory properties. If a property is not necessary, provide it with an empty content.

- `componentID` - The main component ID of the UIMA component that should be packaged

- `mainComponentDesc` - The main component descriptor that should be used to run the PEAR package content

- `classpath` - The classpath settings that must be used to run the PEAR package content - use $main_root macros

- `datapath` - The datapath settings that must be used to run the PEAR package content - use $main_root macros

- `mainComponentDir` - The main component directory that contains the PEAR package content

- `targetDir` - The target directory where the created PEAR package is written to. The filename for the created PEAR package is <componetID>.pear

Additionally it is possible to specify environment variable settings that are necessary to run the PEAR package. This is done with the `<envVar>` element as shown above. The `name` specifies the variable name and the `value` specifies the variable value.