You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2008/08/28 23:28:16 UTC
svn commit: r689997 [20/32] - in /incubator/uima/uimaj/trunk/uima-docbooks:
./ src/ src/docbook/overview_and_setup/ src/docbook/references/
src/docbook/tools/ src/docbook/tutorials_and_users_guides/
src/docbook/uima/organization/ src/olink/references/
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.packager.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.packager.xml?rev=689997&r1=689996&r2=689997&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.packager.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.packager.xml Thu Aug 28 14:28:14 2008
@@ -1,387 +1,387 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
-<!ENTITY imgroot "../images/tools/tools.pear.packager/" >
-<!ENTITY % uimaents SYSTEM "../entities.ent" >
-%uimaents;
-]>
-<!--
-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.
--->
-<chapter id="ugr.tools.pear.packager">
- <title>PEAR Packager User's Guide</title>
-
- <para>A PEAR (Processing Engine ARchive) file is a standard package for UIMA (Unstructured
- Information Management Architecture) components. The PEAR package can be used for
- distribution and reuse by other components or applications. It also allows applications
- and tools to manage UIMA components automatically for verification, deployment,
- invocation, testing, etc. Please refer to <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.pear"/>
- for more information about the internal structure of a PEAR file.</para>
-
- <para>This chapter describes how to use the PEAR Eclipse plugin or the PEAR command line packager
- to create PEAR files for standard UIMA components.</para>
-
- <section id="ugr.tools.pear.packager.using_eclipse_plugin">
- <title>Using the PEAR Eclipse Plugin</title>
-
- <para>The PEAR Eclipse plugin is automatically installed if you followed the directions in
- <olink targetdoc="&uima_docs_overview;" targetptr="ugr.ovv.eclipse_setup"/>. The use of the
- plugin involves the following two steps:</para>
-
- <itemizedlist spacing="compact"><listitem><para>Add the UIMA nature to your project
- </para></listitem>
-
- <listitem><para>Create a PEAR file using the PEAR generation wizard </para>
- </listitem></itemizedlist>
-
- <section id="ugr.tools.pear.packager.add_uima_nature">
- <title>Add UIMA Nature to your project</title>
-
- <para>First, create a project for your UIMA component:</para>
-
- <itemizedlist spacing="compact"><listitem><para>Create a Java project, which
- would contain all the files and folders needed for your UIMA component.</para>
- </listitem>
-
- <listitem><para>Create a source folder called <quote>src</quote> in your
- project, and make it the only source folder, by clicking on
- <quote>Properties</quote> in your project's context menu (right-click),
- then select <quote>Java Build Path</quote>, then add the <quote>src</quote>
- folder to the source folders list, and remove any other folder from the
- list.</para></listitem>
-
- <listitem><para>Specify an output folder for your project called bin, by clicking
- on <quote>Properties</quote> in your project's context menu
- (right-click), then select <quote>Java Build Path</quote>, and specify
- <quote><emphasis>your_project_name</emphasis>/bin</quote> as the default
- output folder. </para></listitem></itemizedlist>
-
- <para>Then, add the UIMA nature to your project by clicking on <quote>Add UIMA
- Nature</quote> in the context menu (right-click) of your project. Click
- <quote>Yes</quote> on the <quote>Adding UIMA custom Nature</quote> dialog box.
- Click <quote>OK</quote> on the confirmation dialog box.
-
-
- <screenshot>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
- </imageobject>
- <textobject><phrase>Screenshot of Adding the UIMA Nature to your project</phrase>
- </textobject>
- </mediaobject>
- </screenshot></para>
-
- <para>Adding the UIMA nature to your project creates the PEAR structure in your
- project. The PEAR structure is a structured tree of folders and files, including the
- following elements:
-
- <itemizedlist><listitem><para><emphasis role="bold">Required
- Elements:</emphasis>
-
- <itemizedlist><listitem><para>The <emphasis role="bold">
- metadata</emphasis> folder which contains the PEAR installation descriptor
- and properties files.</para></listitem>
-
- <listitem><para>The installation descriptor (<emphasis role="bold">
- metadata/install.xml</emphasis>)
- </para></listitem></itemizedlist></para></listitem>
-
- <listitem><para><emphasis role="bold">Optional Elements:</emphasis>
-
- <itemizedlist><listitem><para>The <emphasis role="bold">
- desc</emphasis> folder to contain descriptor files of analysis engines,
- component analysis engines (all levels), and other component (Collection
- Readers, CAS Consumers, etc).</para></listitem>
-
- <listitem><para>The <emphasis role="bold">src </emphasis>folder to
- contain the source code</para></listitem>
-
- <listitem><para>The <emphasis role="bold">bin</emphasis> folder to
- contain executables, scripts, class files, dlls, shared libraries,
- etc.</para></listitem>
-
- <listitem><para>The <emphasis role="bold">lib</emphasis> folder to
- contain jar files. </para></listitem>
-
- <listitem><para>The <emphasis role="bold">doc </emphasis>folder
- containing documentation materials, preferably accessible through an
- index.html.</para></listitem>
-
- <listitem><para>The <emphasis role="bold">data</emphasis> folder to
- contain data files (e.g. for testing).</para></listitem>
-
- <listitem><para>The <emphasis role="bold">conf</emphasis> folder to
- contain configuration files.</para></listitem>
-
- <listitem><para>The <emphasis role="bold">resources</emphasis> folder
- to contain other resources and dependencies.</para></listitem>
-
- <listitem><para>Other user-defined folders or files are allowed, but
- <emphasis>should be avoided</emphasis>. </para></listitem>
- </itemizedlist> </para></listitem></itemizedlist></para>
-
- <para>For more information about the PEAR structure, please refer to the
- <quote>Processing Engine Archive</quote> section.
-
- <figure id="ugr.tools.pear.packager.fig.pear_structure">
- <title>The Pear Structure</title>
- <mediaobject>
- <imageobject>
- <imagedata width="3in" format="JPG"
- fileref="&imgroot;image004.jpg"/>
- </imageobject>
- <textobject><phrase>Pear structure</phrase>
- </textobject>
- </mediaobject>
- </figure></para>
-
- </section>
- <section id="ugr.tools.pear.packager.using_pear_generation_wizard">
- <title>Using the PEAR Generation Wizard</title>
-
- <para>Before using the PEAR Generation Wizard, add all the files needed to
- run your component including descriptors, jars, external libraries, resources,
- and component analysis engines (in the case of an aggregate analysis engine), etc.
- <emphasis>Do not</emphasis> add Jars for the UIMA framework, however. Doing so will
- cause class loading problems at run time.</para>
- <para>
- If you're using a Java IDE like Eclipse, instead of using the output folder (usually
- <literal>bin</literal> as the source of your classes, it's recommended that
- you generate a Jar file containing these classes.</para>
-
- <para>Then, click on <quote>Generate PEAR file</quote> from the context menu
- (right-click) of your project, to open the PEAR Generation wizard, and follow the
- instructions on the wizard to generate the PEAR file.</para>
-
- <section id="ugr.tools.pear.packager.wizard.component_information">
- <title>The Component Information page</title>
-
- <para>The first page of the PEAR generation wizard is the component information
- page. Specify in this page a component ID for your PEAR and select the main Analysis
- Engine descriptor. The descriptor must be specified using a pathname relative to
- the project's root (e.g. <quote>desc/MyAE.xml</quote>). The component id
- is a string that uniquely identifies the component. It should use the JAVA naming
- convention (e.g. org.apache.uima.mycomponent).</para>
-
- <para>Optionally, you can include specific Collection Iterator, CAS Initializer (deprecated
- as of Version 2.1),
- or CAS Consumers. In this case, specify the corresponding descriptors in this
- page.
-
- <figure id="ugr.tools.pear.packager.fig.wizard.component_information">
- <title>The Component Information Page</title>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG"
- fileref="&imgroot;image006.jpg"/>
- </imageobject>
- <textobject><phrase>Pear Wizard - component information page</phrase>
- </textobject>
- </mediaobject>
- </figure></para>
-
- </section>
-
- <section id="ugr.tools.pear.packager.wizard.install_environment">
- <title>The Installation Environment page</title>
-
- <para>The installation environment page is used to specify the following:
-
- <itemizedlist spacing="compact"><listitem><para>Preferred operating
- system</para></listitem>
-
- <listitem><para>Required JDK version, if applicable.</para></listitem>
-
- <listitem><para>Required Environment variable settings. This is where
- you specify special CLASSPATH paths. You do not need to specify this for
- any Jar that is listed in the your eclipse project classpath settings; those are automatically
- put into the generated CLASSPATH. Nor should you include paths to the
- UIMA Framework itself, here. Doing so may cause class loading problems.
- </para>
-
- <para>CLASSPATH segments are written here using a semicolon ";" as the separator;
- during PEAR installation, these will be adjusted to be the correct character for the
- target Operating System.</para>
-
- <para>In order to specify the UIMA datapath for your component you have to create an environment
- variable with the property name <literal>uima.datapath</literal>. The value of this property
- must contain the UIMA datapath settings.</para>
-
- </listitem></itemizedlist></para>
-
- <para>Path names should be specified using macros (see below), instead of
- hard-coded absolute paths that might work locally, but probably won't if the
- PEAR is deployed in a different machine and environment.</para>
-
- <para>Macros are variables such as $main_root, used to represent a string such as the
- full path of a certain directory.</para>
-
- <para>These macros should be defined in the PEAR.properties file using the local
- values. The tools and applications that use and deploy PEAR files should replace
- these macros (in the files included in the conf and desc folders) with the
- corresponding values in the local environment as part of the deployment
- process.</para>
-
- <para>Currently, there are two types of macros:</para>
-
- <itemizedlist><listitem><para>$main_root, which represents the local absolute
- path of the main component root directory after deployment.</para></listitem>
-
- <listitem><para><emphasis>$component_id$root</emphasis>, which
- represents the local absolute path to the root directory of the component which
- has <emphasis>component_id</emphasis> as component ID. This component could
- be, for instance, a delegate component. </para></listitem></itemizedlist>
-
- <figure id="ugr.tools.pear.packager.fig.wizard.install_environment">
- <title>The Installation Environment Page</title>
- <mediaobject>
- <imageobject>
- <imagedata width="5.8in" format="JPG"
- fileref="&imgroot;image008.jpg"/>
- </imageobject>
- <textobject><phrase>Pear Wizard - install environment page</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
- </section>
-
- <section id="ugr.tools.pear.packager.wizard.file_content">
- <title>The PEAR file content page</title>
-
- <para>The last page of the wizard is the <quote>PEAR file Export</quote> page, which
- allows the user to select the files to include in the PEAR file. The metadata folder
- and all its content is mandatory. Make sure you include all the files needed to run
- your component including descriptors, jars, external libraries, resources, and
- component analysis engines (in the case of an aggregate analysis engine), etc.
- It's recommended to generate a jar file from your code as an alternative to
- building the project and making sure the output folder (bin) contains the required
- class files.</para>
-
- <para>Eclipse compiles your class files into some output directory, often named
- "bin" when you take the usual defaults in Eclipse. The recommended practice is to
- take all these files and put them into a Jar file, perhaps using the Eclipse Export
- wizard. You would place that Jar file into the PEAR <literal>lib</literal> directory.</para>
-
- <note><para>If you are relying on the class files generated in the output folder
- (usually called bin) to run your code, then make sure the project is built properly,
- and all the required class files are generated without errors, and then put the
- output folder (e.g. $main_root/bin) in the classpath using the option to set
- environment variables, by setting the CLASSPATH variable to include this folder (see the
- <quote>Installation Environment</quote> page.
- Beware that using a Java output folder named "bin" in this case is a poor practice,
- because the PEAR installation
- tools will presume this folder contains binary executable files, and will adds this folder to
- the PATH environment variable.
- </para> </note>
- <figure id="ugr.tools.pear.packager.fig.wizard.export">
- <title>The PEAR File Export Page</title>
- <mediaobject>
- <imageobject>
- <imagedata width="5.7in" format="JPG"
- fileref="&imgroot;image010.jpg"/>
- </imageobject>
- <textobject><phrase>Pear Wizard - File Export Page</phrase>
- </textobject>
- </mediaobject>
- </figure>
-
-
-
- </section>
- </section>
- </section>
-
- <section id="ugr.tools.pear.packager.using_command_line">
- <title>Using the PEAR command line packager</title>
- <para>The PEAR command line packager takes some PEAR package parameter settings on the command line to create an
- UIMA PEAR file.</para>
-
- <para>To run the PEAR command line packager you can use the provided runPearPackager (.bat for Windows, and .sh for Unix)
- scripts. The packager can be used in three different modes.</para>
- <para><itemizedlist>
- <listitem>
- <para>Mode 1: creates a complete PEAR package with the provided information (default mode)</para>
- <para><programlisting>runPearPackager -compID <componentID>
- -mainCompDesc <mainComponentDesc> [-classpath <classpath>]
- [-datapath <datapath>] -mainCompDir <mainComponentDir>
- -targetDir <targetDir> [-envVars <propertiesFilePath>]</programlisting></para>
- <para> The created PEAR file has the file name <componentID>.pear and is located in the <targetDir>.</para>
- </listitem>
-
- <listitem>
- <para>Mode 2: creates a PEAR installation descriptor without packaging the PEAR file</para>
- <para><programlisting>runPearPackager -create -compID <componentID>
- -mainCompDesc <mainComponentDesc> [-classpath <classpath>]
- [-datapath <datapath>] -mainCompDir <mainComponentDir>
- [-envVars <propertiesFilePath>]</programlisting></para>
- <para> The PEAR installation descriptor is created in the <mainComponentDir>/metadata directory.</para>
- </listitem>
-
- <listitem>
- <para>Mode 3: creates a PEAR package with an existing PEAR installation descriptor</para>
- <para><programlisting>runPearPackager -package -compID <componentID>
- -mainCompDir <mainComponentDir> -targetDir <targetDir></programlisting></para>
- <para> The created PEAR file has the file name <componentID>.pear and is located in the <targetDir>.</para>
- </listitem>
-
- </itemizedlist>
- </para>
- <para>The modes 2 and 3 should be used when you want to manipulate the PEAR installation descriptor before packaging
- the PEAR file. </para>
-
- <para>Some more details about the PearPackager parameters is provided in the list below:</para>
- <para><itemizedlist>
- <listitem>
- <simpara><literal><componentID></literal>: PEAR package component ID.</simpara>
- </listitem>
-
- <listitem>
- <simpara><literal><mainComponentDesc></literal>: Main component descriptor of the PEAR package.</simpara>
- </listitem>
-
- <listitem>
- <simpara><literal><classpath></literal>: PEAR classpath settings. Use $main_root macros to specify
- path entries. Use <literal>;</literal> to separate the entries.</simpara>
- </listitem>
-
- <listitem>
- <simpara><literal><datapath></literal>: PEAR datapath settings. Use $main_root macros to specify
- path entries. Use <literal>;</literal> to separate the path entries.</simpara>
- </listitem>
-
- <listitem>
- <simpara><literal><mainComponentDir></literal>: Main component directory that contains the PEAR package content.</simpara>
- </listitem>
-
- <listitem>
- <simpara><literal><targetDir></literal>: Target directory where the created PEAR file is written to.</simpara>
- </listitem>
-
- <listitem>
- <simpara><literal><propertiesFilePath></literal>: Path name to a properties file that contains environment variables that must be
- set to run the PEAR content.</simpara>
- </listitem>
-
- </itemizedlist>
-
- </para>
- </section>
-
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY imgroot "../images/tools/tools.pear.packager/" >
+<!ENTITY % uimaents SYSTEM "../entities.ent" >
+%uimaents;
+]>
+<!--
+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.
+-->
+<chapter id="ugr.tools.pear.packager">
+ <title>PEAR Packager User's Guide</title>
+
+ <para>A PEAR (Processing Engine ARchive) file is a standard package for UIMA (Unstructured
+ Information Management Architecture) components. The PEAR package can be used for
+ distribution and reuse by other components or applications. It also allows applications
+ and tools to manage UIMA components automatically for verification, deployment,
+ invocation, testing, etc. Please refer to <olink targetdoc="&uima_docs_ref;" targetptr="ugr.ref.pear"/>
+ for more information about the internal structure of a PEAR file.</para>
+
+ <para>This chapter describes how to use the PEAR Eclipse plugin or the PEAR command line packager
+ to create PEAR files for standard UIMA components.</para>
+
+ <section id="ugr.tools.pear.packager.using_eclipse_plugin">
+ <title>Using the PEAR Eclipse Plugin</title>
+
+ <para>The PEAR Eclipse plugin is automatically installed if you followed the directions in
+ <olink targetdoc="&uima_docs_overview;" targetptr="ugr.ovv.eclipse_setup"/>. The use of the
+ plugin involves the following two steps:</para>
+
+ <itemizedlist spacing="compact"><listitem><para>Add the UIMA nature to your project
+ </para></listitem>
+
+ <listitem><para>Create a PEAR file using the PEAR generation wizard </para>
+ </listitem></itemizedlist>
+
+ <section id="ugr.tools.pear.packager.add_uima_nature">
+ <title>Add UIMA Nature to your project</title>
+
+ <para>First, create a project for your UIMA component:</para>
+
+ <itemizedlist spacing="compact"><listitem><para>Create a Java project, which
+ would contain all the files and folders needed for your UIMA component.</para>
+ </listitem>
+
+ <listitem><para>Create a source folder called <quote>src</quote> in your
+ project, and make it the only source folder, by clicking on
+ <quote>Properties</quote> in your project's context menu (right-click),
+ then select <quote>Java Build Path</quote>, then add the <quote>src</quote>
+ folder to the source folders list, and remove any other folder from the
+ list.</para></listitem>
+
+ <listitem><para>Specify an output folder for your project called bin, by clicking
+ on <quote>Properties</quote> in your project's context menu
+ (right-click), then select <quote>Java Build Path</quote>, and specify
+ <quote><emphasis>your_project_name</emphasis>/bin</quote> as the default
+ output folder. </para></listitem></itemizedlist>
+
+ <para>Then, add the UIMA nature to your project by clicking on <quote>Add UIMA
+ Nature</quote> in the context menu (right-click) of your project. Click
+ <quote>Yes</quote> on the <quote>Adding UIMA custom Nature</quote> dialog box.
+ Click <quote>OK</quote> on the confirmation dialog box.
+
+
+ <screenshot>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG" fileref="&imgroot;image002.jpg"/>
+ </imageobject>
+ <textobject><phrase>Screenshot of Adding the UIMA Nature to your project</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot></para>
+
+ <para>Adding the UIMA nature to your project creates the PEAR structure in your
+ project. The PEAR structure is a structured tree of folders and files, including the
+ following elements:
+
+ <itemizedlist><listitem><para><emphasis role="bold">Required
+ Elements:</emphasis>
+
+ <itemizedlist><listitem><para>The <emphasis role="bold">
+ metadata</emphasis> folder which contains the PEAR installation descriptor
+ and properties files.</para></listitem>
+
+ <listitem><para>The installation descriptor (<emphasis role="bold">
+ metadata/install.xml</emphasis>)
+ </para></listitem></itemizedlist></para></listitem>
+
+ <listitem><para><emphasis role="bold">Optional Elements:</emphasis>
+
+ <itemizedlist><listitem><para>The <emphasis role="bold">
+ desc</emphasis> folder to contain descriptor files of analysis engines,
+ component analysis engines (all levels), and other component (Collection
+ Readers, CAS Consumers, etc).</para></listitem>
+
+ <listitem><para>The <emphasis role="bold">src </emphasis>folder to
+ contain the source code</para></listitem>
+
+ <listitem><para>The <emphasis role="bold">bin</emphasis> folder to
+ contain executables, scripts, class files, dlls, shared libraries,
+ etc.</para></listitem>
+
+ <listitem><para>The <emphasis role="bold">lib</emphasis> folder to
+ contain jar files. </para></listitem>
+
+ <listitem><para>The <emphasis role="bold">doc </emphasis>folder
+ containing documentation materials, preferably accessible through an
+ index.html.</para></listitem>
+
+ <listitem><para>The <emphasis role="bold">data</emphasis> folder to
+ contain data files (e.g. for testing).</para></listitem>
+
+ <listitem><para>The <emphasis role="bold">conf</emphasis> folder to
+ contain configuration files.</para></listitem>
+
+ <listitem><para>The <emphasis role="bold">resources</emphasis> folder
+ to contain other resources and dependencies.</para></listitem>
+
+ <listitem><para>Other user-defined folders or files are allowed, but
+ <emphasis>should be avoided</emphasis>. </para></listitem>
+ </itemizedlist> </para></listitem></itemizedlist></para>
+
+ <para>For more information about the PEAR structure, please refer to the
+ <quote>Processing Engine Archive</quote> section.
+
+ <figure id="ugr.tools.pear.packager.fig.pear_structure">
+ <title>The Pear Structure</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="3in" format="JPG"
+ fileref="&imgroot;image004.jpg"/>
+ </imageobject>
+ <textobject><phrase>Pear structure</phrase>
+ </textobject>
+ </mediaobject>
+ </figure></para>
+
+ </section>
+ <section id="ugr.tools.pear.packager.using_pear_generation_wizard">
+ <title>Using the PEAR Generation Wizard</title>
+
+ <para>Before using the PEAR Generation Wizard, add all the files needed to
+ run your component including descriptors, jars, external libraries, resources,
+ and component analysis engines (in the case of an aggregate analysis engine), etc.
+ <emphasis>Do not</emphasis> add Jars for the UIMA framework, however. Doing so will
+ cause class loading problems at run time.</para>
+ <para>
+ If you're using a Java IDE like Eclipse, instead of using the output folder (usually
+ <literal>bin</literal> as the source of your classes, it's recommended that
+ you generate a Jar file containing these classes.</para>
+
+ <para>Then, click on <quote>Generate PEAR file</quote> from the context menu
+ (right-click) of your project, to open the PEAR Generation wizard, and follow the
+ instructions on the wizard to generate the PEAR file.</para>
+
+ <section id="ugr.tools.pear.packager.wizard.component_information">
+ <title>The Component Information page</title>
+
+ <para>The first page of the PEAR generation wizard is the component information
+ page. Specify in this page a component ID for your PEAR and select the main Analysis
+ Engine descriptor. The descriptor must be specified using a pathname relative to
+ the project's root (e.g. <quote>desc/MyAE.xml</quote>). The component id
+ is a string that uniquely identifies the component. It should use the JAVA naming
+ convention (e.g. org.apache.uima.mycomponent).</para>
+
+ <para>Optionally, you can include specific Collection Iterator, CAS Initializer (deprecated
+ as of Version 2.1),
+ or CAS Consumers. In this case, specify the corresponding descriptors in this
+ page.
+
+ <figure id="ugr.tools.pear.packager.fig.wizard.component_information">
+ <title>The Component Information Page</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG"
+ fileref="&imgroot;image006.jpg"/>
+ </imageobject>
+ <textobject><phrase>Pear Wizard - component information page</phrase>
+ </textobject>
+ </mediaobject>
+ </figure></para>
+
+ </section>
+
+ <section id="ugr.tools.pear.packager.wizard.install_environment">
+ <title>The Installation Environment page</title>
+
+ <para>The installation environment page is used to specify the following:
+
+ <itemizedlist spacing="compact"><listitem><para>Preferred operating
+ system</para></listitem>
+
+ <listitem><para>Required JDK version, if applicable.</para></listitem>
+
+ <listitem><para>Required Environment variable settings. This is where
+ you specify special CLASSPATH paths. You do not need to specify this for
+ any Jar that is listed in the your eclipse project classpath settings; those are automatically
+ put into the generated CLASSPATH. Nor should you include paths to the
+ UIMA Framework itself, here. Doing so may cause class loading problems.
+ </para>
+
+ <para>CLASSPATH segments are written here using a semicolon ";" as the separator;
+ during PEAR installation, these will be adjusted to be the correct character for the
+ target Operating System.</para>
+
+ <para>In order to specify the UIMA datapath for your component you have to create an environment
+ variable with the property name <literal>uima.datapath</literal>. The value of this property
+ must contain the UIMA datapath settings.</para>
+
+ </listitem></itemizedlist></para>
+
+ <para>Path names should be specified using macros (see below), instead of
+ hard-coded absolute paths that might work locally, but probably won't if the
+ PEAR is deployed in a different machine and environment.</para>
+
+ <para>Macros are variables such as $main_root, used to represent a string such as the
+ full path of a certain directory.</para>
+
+ <para>These macros should be defined in the PEAR.properties file using the local
+ values. The tools and applications that use and deploy PEAR files should replace
+ these macros (in the files included in the conf and desc folders) with the
+ corresponding values in the local environment as part of the deployment
+ process.</para>
+
+ <para>Currently, there are two types of macros:</para>
+
+ <itemizedlist><listitem><para>$main_root, which represents the local absolute
+ path of the main component root directory after deployment.</para></listitem>
+
+ <listitem><para><emphasis>$component_id$root</emphasis>, which
+ represents the local absolute path to the root directory of the component which
+ has <emphasis>component_id</emphasis> as component ID. This component could
+ be, for instance, a delegate component. </para></listitem></itemizedlist>
+
+ <figure id="ugr.tools.pear.packager.fig.wizard.install_environment">
+ <title>The Installation Environment Page</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.8in" format="JPG"
+ fileref="&imgroot;image008.jpg"/>
+ </imageobject>
+ <textobject><phrase>Pear Wizard - install environment page</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+ </section>
+
+ <section id="ugr.tools.pear.packager.wizard.file_content">
+ <title>The PEAR file content page</title>
+
+ <para>The last page of the wizard is the <quote>PEAR file Export</quote> page, which
+ allows the user to select the files to include in the PEAR file. The metadata folder
+ and all its content is mandatory. Make sure you include all the files needed to run
+ your component including descriptors, jars, external libraries, resources, and
+ component analysis engines (in the case of an aggregate analysis engine), etc.
+ It's recommended to generate a jar file from your code as an alternative to
+ building the project and making sure the output folder (bin) contains the required
+ class files.</para>
+
+ <para>Eclipse compiles your class files into some output directory, often named
+ "bin" when you take the usual defaults in Eclipse. The recommended practice is to
+ take all these files and put them into a Jar file, perhaps using the Eclipse Export
+ wizard. You would place that Jar file into the PEAR <literal>lib</literal> directory.</para>
+
+ <note><para>If you are relying on the class files generated in the output folder
+ (usually called bin) to run your code, then make sure the project is built properly,
+ and all the required class files are generated without errors, and then put the
+ output folder (e.g. $main_root/bin) in the classpath using the option to set
+ environment variables, by setting the CLASSPATH variable to include this folder (see the
+ <quote>Installation Environment</quote> page.
+ Beware that using a Java output folder named "bin" in this case is a poor practice,
+ because the PEAR installation
+ tools will presume this folder contains binary executable files, and will adds this folder to
+ the PATH environment variable.
+ </para> </note>
+ <figure id="ugr.tools.pear.packager.fig.wizard.export">
+ <title>The PEAR File Export Page</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata width="5.7in" format="JPG"
+ fileref="&imgroot;image010.jpg"/>
+ </imageobject>
+ <textobject><phrase>Pear Wizard - File Export Page</phrase>
+ </textobject>
+ </mediaobject>
+ </figure>
+
+
+
+ </section>
+ </section>
+ </section>
+
+ <section id="ugr.tools.pear.packager.using_command_line">
+ <title>Using the PEAR command line packager</title>
+ <para>The PEAR command line packager takes some PEAR package parameter settings on the command line to create an
+ UIMA PEAR file.</para>
+
+ <para>To run the PEAR command line packager you can use the provided runPearPackager (.bat for Windows, and .sh for Unix)
+ scripts. The packager can be used in three different modes.</para>
+ <para><itemizedlist>
+ <listitem>
+ <para>Mode 1: creates a complete PEAR package with the provided information (default mode)</para>
+ <para><programlisting>runPearPackager -compID <componentID>
+ -mainCompDesc <mainComponentDesc> [-classpath <classpath>]
+ [-datapath <datapath>] -mainCompDir <mainComponentDir>
+ -targetDir <targetDir> [-envVars <propertiesFilePath>]</programlisting></para>
+ <para> The created PEAR file has the file name <componentID>.pear and is located in the <targetDir>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Mode 2: creates a PEAR installation descriptor without packaging the PEAR file</para>
+ <para><programlisting>runPearPackager -create -compID <componentID>
+ -mainCompDesc <mainComponentDesc> [-classpath <classpath>]
+ [-datapath <datapath>] -mainCompDir <mainComponentDir>
+ [-envVars <propertiesFilePath>]</programlisting></para>
+ <para> The PEAR installation descriptor is created in the <mainComponentDir>/metadata directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>Mode 3: creates a PEAR package with an existing PEAR installation descriptor</para>
+ <para><programlisting>runPearPackager -package -compID <componentID>
+ -mainCompDir <mainComponentDir> -targetDir <targetDir></programlisting></para>
+ <para> The created PEAR file has the file name <componentID>.pear and is located in the <targetDir>.</para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ <para>The modes 2 and 3 should be used when you want to manipulate the PEAR installation descriptor before packaging
+ the PEAR file. </para>
+
+ <para>Some more details about the PearPackager parameters is provided in the list below:</para>
+ <para><itemizedlist>
+ <listitem>
+ <simpara><literal><componentID></literal>: PEAR package component ID.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><literal><mainComponentDesc></literal>: Main component descriptor of the PEAR package.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><literal><classpath></literal>: PEAR classpath settings. Use $main_root macros to specify
+ path entries. Use <literal>;</literal> to separate the entries.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><literal><datapath></literal>: PEAR datapath settings. Use $main_root macros to specify
+ path entries. Use <literal>;</literal> to separate the path entries.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><literal><mainComponentDir></literal>: Main component directory that contains the PEAR package content.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><literal><targetDir></literal>: Target directory where the created PEAR file is written to.</simpara>
+ </listitem>
+
+ <listitem>
+ <simpara><literal><propertiesFilePath></literal>: Path name to a properties file that contains environment variables that must be
+ set to run the PEAR content.</simpara>
+ </listitem>
+
+ </itemizedlist>
+
+ </para>
+ </section>
+
</chapter>
\ No newline at end of file
Propchange: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.pear.packager.xml
------------------------------------------------------------------------------
svn:eol-style = native
Modified: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.xml
URL: http://svn.apache.org/viewvc/incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.xml?rev=689997&r1=689996&r2=689997&view=diff
==============================================================================
--- incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.xml (original)
+++ incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.xml Thu Aug 28 14:28:14 2008
@@ -1,41 +1,41 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
- <!ENTITY % xinclude SYSTEM "../../../../uima-docbook-tool/xinclude.mod">
- %xinclude;
- ]>
-<!--
-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.
--->
-<book lang="en">
- <title>UIMA Tools Guide and Reference</title>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../common_book_info.xml"/>
- <toc/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.cde.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.cpe.xml"/>
- <!--
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.eclipse_launcher.xml"/>
- -->
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.doc_analyzer.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.annotation_viewer.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.cvd.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.jcasgen.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.pear.packager.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.pear.installer.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.pear.merger.xml"/>
-</book>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+ <!ENTITY % xinclude SYSTEM "../../../../uima-docbook-tool/xinclude.mod">
+ %xinclude;
+ ]>
+<!--
+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.
+-->
+<book lang="en">
+ <title>UIMA Tools Guide and Reference</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../common_book_info.xml"/>
+ <toc/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.cde.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.cpe.xml"/>
+ <!--
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.eclipse_launcher.xml"/>
+ -->
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.doc_analyzer.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.annotation_viewer.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.cvd.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.jcasgen.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.pear.packager.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.pear.installer.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tools.pear.merger.xml"/>
+</book>
Propchange: incubator/uima/uimaj/trunk/uima-docbooks/src/docbook/tools/tools.xml
------------------------------------------------------------------------------
svn:eol-style = native