<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->
<html>
  <head>
    <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"/>
    <title>PEAR Installer Help</title>
  </head>
  <body>
    <h4 style="margin-left: 40px; text-decoration: underline;">Packaging and
      Installing UIMA Components</h4>
    <div style="margin-left: 40px;">PEAR (Processing Engine ARchive) is a standard for
      packaging UIMA compliant components. This standard defines several service elements that should be included
      in the archive package to enable automated installation of the encapsulated UIMA component. The major PEAR
      service element is XML Installation Descriptor that specifies installation platform, component
      attributes, custom installation procedures and environment variables. The
      automated installation of a UIMA compliant component includes 2 steps: (1) installation of the component code
      and resources in a local file system, and (2) verification of the serviceability of the installed component.
      Installation of the component code and resources involves extracting component files from the archive (PEAR)
      package in a designated directory and localizing file references in component descriptors and other
      configuration files. Verification of the component serviceability is
      accomplished with the help of standard UIMA mechanisms for instantiating analysis engines.
    </div>
    <div style="margin-left: 40px;"> <b>PEAR Installer</b> application allows installing
      UIMA compliant components (analysis engines) from PEAR packages in a local file system and run installed
      components using the UIMA CAS Visual Debugger application.
      
    </div>
    <h4 style="margin-left: 40px; text-decoration: underline;">Checking PEAR Installer
      prerequisites and files: </h4>
    <ul>
      <li>Make sure you have J2SE 1.4.2 or later JRE installed
      </li>
      <li>Make sure UIMA is properly installed and <code>UIMA_HOME</code> environment variable
        is set
      </li>
    </ul>
    <h4 style="margin-left: 40px; text-decoration: underline;"> Running PEAR Installer
      application: </h4>
    <ol>
      <li>Start PEAR Installer application by using the <code>runPearInstaller.bat</code>
        script in the <code>%UIMA_HOME%/bin</code> directory. 
      </li>
      <li>Select PEAR file by using the "Browse ..." button on the right of the "PEAR file" text
        field. Alternatively,&nbsp; you can type the PEAR file path in the  "PEAR file" text
        field and press 'Enter'.  Selected file path will appear in both&nbsp; the text
        field and the message area. 
      </li>
      <li>Select the installation directory by using the "Browse Dir ..." button on the right of the
        "Installation Directory" text field. Alternatively, you can type the installation directory path in the
         "Installation Directory" text field a nd press 'Enter'.
        Selected directory path will appear in both the text field and the message area. By
        default, PEAR Installer will use current working directory as the installation directory.
        
        <span style="font-weight: bold; font-style: italic;"> Note</span>: PEAR Installer creates a
        subdirectory in the specified installation directory, using the UIMA component ID as the subdirectory
        name, for the component code and resource files.
      </li>
      <li>Start selected PEAR installation by using the "Install" button. During the
        installation several messages will be printed in the message area.
        
        <span style="font-weight: bold; font-style: italic;"> Note</span>: PEAR Installer creates the
        <code>setenv.txt</code> file in the <code>&lt;component_root&gt;/metadata</code> directory. This
        file contains environment variables required by the component.
      </li>
      <li>If the installation and verification steps completed successfully, you can run your
        component in the UIMA CAS Visual Debugger application by using the "Run your AE in the CAS Visual Debugger"
        button. The CAS Visual Debugger application will load your UIMA component using its XML descriptor file. If
        the component is loaded successfully, you'll we able to run it either with sample documents provided in the
        <code>%UIMA_HOME%/docs/examples/data</code> directory, or with any other sample documents. See UIMA
        documentation for more information about the UIMA CAS Visual Debugger application. 
      </li>
    </ol>
  </body>
</html>