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 2010/05/06 16:04:11 UTC
svn commit: r941741 [4/4] - in
/uima/uimaj/branches/mavenAlign/uima-docbook-tools: ./ src/ src/docbook/
src/docbook/images/ src/docbook/images/tools/
src/docbook/images/tools/tools.annotation_viewer/
src/docbook/images/tools/tools.caseditor/ src/docboo...
Added: uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.maven.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.maven.xml?rev=941741&view=auto
==============================================================================
--- uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.maven.xml (added)
+++ uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.maven.xml Thu May 6 14:04:08 2010
@@ -0,0 +1,385 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
+<!ENTITY imgroot "images/tools/tools.pear.packager.maven/" >
+<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/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.maven.plugin.usage">
+ <title>The PEAR Packaging Maven Plugin</title>
+ <para>
+ UIMA includes a Maven plugin that supports creating PEAR packages using Maven.
+ When configured for a project, it assumes that the project has the PEAR layout,
+ and will copy the standard directories that are part of a PEAR structure under the
+ project root into the PEAR, excluding files that start with a period (".").
+ It also will put the Jar that is built for the project
+ into the lib/ directory and include it first on the generated classpath.
+ </para>
+
+ <para>
+ The classpath that is generated for this includes the artifact's Jar first, any user specified
+ entries second (in the order they are specified), and finally, entries for all Jars
+ found in the lib/ directory (in some arbitrary order).
+ </para>
+
+ <section id="ugr.tools.pear.packager.maven.plugin.usage.configure">
+ <title>Specifying the PEAR Packaging Maven Plugin</title>
+
+ <para>
+ To use the PEAR Packaging Plugin within a Maven build,
+ the plugin must be added to the plugins section of the
+ Maven POM as shown below:
+ </para>
+ <para>
+ <programlisting><![CDATA[<build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.uima</groupId>
+ <artifactId>PearPackagingMavenPlugin</artifactId>
+
+ <!-- if version is omitted, then -->
+ <!-- version is inherited from parent's pluginManagement section -->
+ <!-- otherwise, include a version element here -->
+
+ <!-- says to load Maven extensions
+ (such as packaging and type handlers) from this plugin -->
+ <extensions>true</extensions>
+ <executions>
+ <execution>
+ <phase>package</phase>
+ <!-- where you specify details of the thing being packaged -->
+ <configuration>
+
+ <classpath>
+ <!-- PEAR file component classpath settings -->
+ $main_root/lib/sample.jar
+ </classpath>
+
+ <mainComponentDesc>
+ <!-- PEAR file main component descriptor -->
+ desc/${artifactId}.xml
+ </mainComponentDesc>
+
+ <componentId>
+ <!-- PEAR file component ID -->
+ ${artifactId}
+ </componentId>
+
+ <datapath>
+ <!-- PEAR file UIMA datapath settings -->
+ $main_root/resources
+ </datapath>
+
+ </configuration>
+ <goals>
+ <goal>package</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+</build>
+]]></programlisting>
+ </para>
+
+ <para>
+ To configure the plugin with the specific settings of a PEAR package, the
+ <code><configuration></code> element section is used. This sections contains all parameters
+ that are used by the PEAR Packaging Plugin to package the right content and set the specific PEAR package settings.
+ The details about each parameter and how it is used is shown below:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code><classpath></code>
+ - This element specifies the classpath settings for the
+ PEAR component. The Jar artifact that is built during the current Maven build is
+ automatically added to the PEAR classpath settings and does not have to be added manually.
+ In addition, all Jars in the lib directory and its subdirectories will be added to the
+ generated classpath when the PEAR is installed.
+ </para>
+ <note>
+ <para>Use $main_root variables to refer to libraries inside
+ the PEAR package. For more details about PEAR packaging please refer to the
+ Apache UIMA PEAR documentation.</para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ <code><mainComponentDesc></code>
+ - This element specifies the relative path to the main component descriptor
+ that should be used to run the PEAR content. The path must be relative to the
+ project root. A good default to use is <code>desc/${artifactId}.xml</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code><componentID></code>
+ - This element specifies the PEAR package component ID. A good default
+ to use is <code>${artifactId}</code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code><datapath></code>
+ - This element specifies the PEAR package UIMA datapath settings.
+ If no datapath settings are necessary, this element can be omitted.
+ </para>
+ <note>
+ <para>Use $main_root variables to refer libraries inside
+ the PEAR package. For more details about PEAR packaging please refer to the
+ Apache UIMA PEAR documentation.</para>
+ </note>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ For most Maven projects it is sufficient to specify the parameters described above. In some cases, for
+ more complex projects, it may be necessary to specify some additional configuration
+ parameters. These parameters are listed below with the default values that are used if they are not
+ added to the configuration section shown above.
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <code><mainComponentDir></code>
+ - This element specifies the main component directory where the UIMA
+ nature is applied. By default this parameter points to the project root
+ directory - ${basedir}.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <code><targetDir></code>
+ - This element specifies the target directory where the result of the plugin
+ are written to. By default this parameters points to the default Maven output
+ directory - ${basedir}/target
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="ugr.tools.pear.packager.maven.plugin.usage.dependencies">
+ <title>Automatically including dependencies</title>
+
+ <para>
+ A key concept in PEARs is that they allow specifying other Jars in the classpath.
+ You can optionally include these Jars within the PEAR package.
+ </para>
+ <para>
+ The PEAR Packaging Plugin does not take care of automatically
+ adding these Jars (that the PEAR might depend on) to the PEAR archive.
+ However, this
+ behavior can be manually added to your Maven POM.
+ The following two build plugins
+ hook into the build cycle and insure that all runtime
+ dependencies are included in the PEAR file.
+ </para>
+
+
+ <para>
+ The dependencies will be automatically included in the
+ PEAR file using this procedure; the pear install process also will automatically
+ adds all files in the lib directory (and sub directories) to the
+ classpath.
+ </para>
+
+
+ <para>
+ The <code>maven-dependency-plugin</code>
+ copies the runtime dependencies of the PEAR into the
+ <code>lib</code> folder, which is where the PEAR packaging
+ plugin expects them.
+ </para>
+
+ <programlisting><![CDATA[<build>
+ <plugins>
+ ...
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <!-- Copy the dependencies to the lib folder for the PEAR to copy -->
+ <execution>
+ <id>copy-dependencies</id>
+ <phase>package</phase>
+ <goals>
+ <goal>copy-dependencies</goal>
+ </goals>
+ <configuration>
+ <outputDirectory>${basedir}/lib</outputDirectory>
+ <overWriteSnapshots>true</overWriteSnapshots>
+ <includeScope>runtime</includeScope>
+ </configuration>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+</build>
+]]></programlisting>
+
+ <para>
+ The second Maven plug-in hooks into the <code>clean</code>
+ phase of the build life-cycle, and deletes the
+ <code>lib</code> folder.
+ </para>
+
+ <note>
+ <para>
+ With this approach, the <code>lib</code> folder is
+ automatically created, populated, and removed
+ during the build process. Therefore it should not go into
+ the source control system and neither should you
+ manually place any jars in there.
+ </para>
+ </note>
+
+ <programlisting><![CDATA[<build>
+ <plugins>
+ ...
+ <plugin>
+ <artifactId>maven-antrun-plugin</artifactId>
+ <executions>
+ <!-- Clean the libraries after packaging -->
+ <execution>
+ <id>CleanLib</id>
+ <phase>clean</phase>
+ <configuration>
+ <tasks>
+ <delete quiet="true"
+ failOnError="false">
+ <fileset dir="lib" includes="**/*.jar"/>
+ </delete>
+ </tasks>
+ </configuration>
+ <goals>
+ <goal>run</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ ...
+ </plugins>
+</build>
+]]></programlisting>
+
+ </section>
+
+ <section id="ugr.tools.pear.packager.maven.plugin.install">
+ <title>Installing The PEAR Packaging Plugin</title>
+
+ <para>If you specify the Apache Incubating Repository as one of the repositories
+ for your maven configuration, then the <code>uima-pear-maven-plugin.jar</code>
+ will be automatically fetched when needed.
+ This is typically specified in the POM, the Maven .settings file or in
+ a parent POM, using this format:
+ </para>
+ <programlisting><![CDATA[<repositories>
+ <repository>
+ <id>apache-incubating-repository</id>
+ <url>http://people.apache.org/repo/m2-incubating-repository</url>
+ <releases>
+ <!-- never: because artifacts are never updated in the repo -->
+ <updatePolicy>never</updatePolicy>
+ </releases>
+ </repository>
+</repositories>]]></programlisting>
+
+ <para>
+ Otherwise, the
+ <code>uima-pear-maven-plugin.jar</code> file must be manually installed into your local
+ repository. See <ulink url="http://maven.apache.org/general.html#importing-jars"/>.
+ The information you need to do this is:
+ <itemizedlist spacing="compact">
+ <listitem><para><code>-DgroupId=org.apache.uima</code></para></listitem>
+ <listitem><para><code>-DartifactId=PearPackagingMavenPlugin</code></para></listitem>
+ <listitem><para><code>-Dversion=2.3.0-incubating</code> (change this to the version you want)</para></listitem>
+ <listitem><para><code>-Dpackaging=jar</code></para></listitem>
+ <listitem><para><code>-DgeneratePom=true</code></para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="ugr.tools.pear.packager.maven.plugin.commandline">
+ <title>Running from the command line</title>
+ <para>
+ The pear packager can be run as a maven command. To enable this, you have to add the following to your
+ maven settings file:
+ <programlisting><![CDATA[<settings>
+ ...
+ <pluginGroups>
+ <pluginGroup>org.apache.uima</pluginGroup>
+ </pluginGroups>]]></programlisting>
+ To invoke the pear packager using maven, use the command:
+ <programlisting><![CDATA[mvn uima-pear:package <parameters...>]]></programlisting>
+ The settings are the same ones used in the configuration above, specified as -D variables
+ where the variable name is pear.parameterName.
+ For example:
+ <programlisting><![CDATA[mvn uima-pear:package -Dpear.mainComponentDesc=desc/mydescriptor.xml
+ -Dpear.componentId=foo]]></programlisting>
+ </para>
+ </section>
+
+ <section id="ugr.tools.pear.packager.maven.plugin.install.src">
+ <title>Building the PEAR Packaging Plugin From Source</title>
+ <para>
+ The plugin code is available in the Apache
+ subversion repository at:
+ <ulink url="http://svn.apache.org/repos/asf/incubator/uima/uimaj/trunk/PearPackagingMavenPlugin"/>.
+ Use the following command line to build it (you will need the Maven build tool, available from Apache):
+ </para>
+ <para>
+ <programlisting><![CDATA[#PearPackagingMavenPlugin> mvn install]]></programlisting>
+ </para>
+ <para>
+ This maven command will build the tool and install it in your local maven repository,
+ making it available for use by other maven POMs. The plugin version number
+ is displayed at the end of the Maven build as shown in the example below. For this example, the plugin
+ version number is: <code>2.3.0-incubating</code>
+ </para>
+ <para>
+ <programlisting><![CDATA[[INFO] Installing
+/code/apache/PearPackagingMavenPlugin/target/
+PearPackagingMavenPlugin-2.3.0-incubating.jar
+to
+/maven-repository/repository/org/apache/uima/PearPackagingMavenPlugin/
+2.3.0-incubating/
+PearPackagingMavenPlugin-2.3.0-incubating.jar
+[INFO] [plugin:updateRegistry]
+[INFO] --------------------------------------------------------------
+[INFO] BUILD SUCCESSFUL
+[INFO] --------------------------------------------------------------
+[INFO] Total time: 6 seconds
+[INFO] Finished at: Tue Nov 13 15:07:11 CET 2007
+[INFO] Final Memory: 10M/24M
+[INFO] --------------------------------------------------------------]]></programlisting>
+ </para>
+ </section>
+</chapter>
+
+
Added: uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.xml?rev=941741&view=auto
==============================================================================
--- uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.xml (added)
+++ uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.pear.packager.xml Thu May 6 14:04:08 2010
@@ -0,0 +1,387 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"[
+<!ENTITY imgroot "images/tools/tools.pear.packager/" >
+<!ENTITY % uimaents SYSTEM "../../target/docbook-shared/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
Added: uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.xml
URL: http://svn.apache.org/viewvc/uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.xml?rev=941741&view=auto
==============================================================================
--- uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.xml (added)
+++ uima/uimaj/branches/mavenAlign/uima-docbook-tools/src/docbook/tools.xml Thu May 6 14:04:08 2010
@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<!--
+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="../../target/docbook-shared/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.caseditor.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.packager.maven.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>