You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by ea...@apache.org on 2007/04/24 16:40:18 UTC
svn commit: r531960 - in /incubator/uima/uimacpp/trunk: buildSrcTree.cmd
docs/QuickStart.html docs/overview_and_setup.html examples/readme.html
scriptators/perl/Perl.html scriptators/python/Python.html
scriptators/tcl/Tcl.html
Author: eae
Date: Tue Apr 24 07:40:14 2007
New Revision: 531960
URL: http://svn.apache.org/viewvc?view=rev&rev=531960
Log:
UIMA-275
Added:
incubator/uima/uimacpp/trunk/docs/overview_and_setup.html
Removed:
incubator/uima/uimacpp/trunk/docs/QuickStart.html
Modified:
incubator/uima/uimacpp/trunk/buildSrcTree.cmd
incubator/uima/uimacpp/trunk/examples/readme.html
incubator/uima/uimacpp/trunk/scriptators/perl/Perl.html
incubator/uima/uimacpp/trunk/scriptators/python/Python.html
incubator/uima/uimacpp/trunk/scriptators/tcl/Tcl.html
Modified: incubator/uima/uimacpp/trunk/buildSrcTree.cmd
URL: http://svn.apache.org/viewvc/incubator/uima/uimacpp/trunk/buildSrcTree.cmd?view=diff&rev=531960&r1=531959&r2=531960
==============================================================================
--- incubator/uima/uimacpp/trunk/buildSrcTree.cmd (original)
+++ incubator/uima/uimacpp/trunk/buildSrcTree.cmd Tue Apr 24 07:40:14 2007
@@ -161,6 +161,9 @@
xcopy /Q %UIMACPP_SOURCE%\scriptators\tcl\*.* %TARGET_DIR%\scriptators\tcl
del %TARGET_DIR%\scriptators\tcl\Makefile
+echo cleaning the target tree
+for /R %TARGET_DIR% %%d in (.) do del %%d\*~ 2> NUL
+
echo DONE ... Source image created in %TARGET_DIR%
goto end
Added: incubator/uima/uimacpp/trunk/docs/overview_and_setup.html
URL: http://svn.apache.org/viewvc/incubator/uima/uimacpp/trunk/docs/overview_and_setup.html?view=auto&rev=531960
==============================================================================
--- incubator/uima/uimacpp/trunk/docs/overview_and_setup.html (added)
+++ incubator/uima/uimacpp/trunk/docs/overview_and_setup.html Tue Apr 24 07:40:14 2007
@@ -0,0 +1,251 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+ <title>C++ Overview and Setup</title>
+ <link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
+ </head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en" id="d0e2"><div class="titlepage"><div><div><h1 class="title"><a name="d0e2"></a>Overview & Setup</h1></div><div><div class="authorgroup"><h3 class="corpauthor">Authors: The Apache UIMA Development Community</h3></div></div><div><p class="releaseinfo">Version 2.1</p></div><div><p class="copyright">Copyright © 2006, 2007 The Apache Software Foundation</p></div><div><p class="copyright">Copyright © 2004, 2006 International Business Machines Corporation</p></div><div><div class="legalnotice"><a name="d0e15"></a><p> </p><p><b>Incubation Notice and Disclaimer. </b>Apache UIMA is an effort undergoing incubation at the Apache Software Foundation (ASF).
+ Incubation is required of all newly accepted projects until a further review indicates that
+ the infrastructure, communications, and decision making process have stabilized in a manner
+ consistent with other successful ASF projects. While incubation status is not necessarily
+ a reflection of the completeness or stability of the code,
+ it does indicate that the project has yet to be fully endorsed by the ASF.</p><p> </p><p> </p><p><b>License and Disclaimer. </b>The ASF licenses this documentation
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this documentation except in compliance
+ with the License. You may obtain a copy of the License at
+
+ </p><div class="blockquote"><blockquote class="blockquote"><a href="http://www.apache.org/licenses/LICENSE-2.0" target="_top">http://www.apache.org/licenses/LICENSE-2.0</a></blockquote></div><p>
+
+ Unless required by applicable law or agreed to in writing,
+ this documentation and its contents are distributed under the License
+ 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.
+ </p><p> </p><p> </p><p><b>Trademarks. </b>All terms mentioned in the text that are known to be trademarks or
+ service marks have been appropriately capitalized. Use of such terms
+ in this book should not be regarded as affecting the validity of the
+ the trademark or service mark.
+ </p></div></div><div><p class="pubdate">February, 2007</p></div></div><hr></div>
+
+
+
+<h2>1.0 UIMA C++ Overview</h2>
+<p>The UIMA C++ framework is primarily intended to facilitate the creation of UIMA compliant
+analysis engines from analytics written in C/C++. The rich set of CAS interface methods minimizes
+the effort to extract input data from a CAS and then update the CAS with the analytic results.
+The UIMA C++ framework transparently moves the CAS from Java to C++ environments, and from a UIMA
+client to a UIMA service.
+</p>
+<p>
+A UIMA C++ component is identified as such to the framework by specifying in its
+component descriptor:
+ <ul>
+ <code><frameworkImplementation>org.apache.uima.cpp</frameworkImplementation></code>
+ </ul>
+</p>
+<p>The UIMA C++ framework supports embedding UIMA components in a native process. There are APIs to
+parse component descriptors, instantiate and call analysis engines.
+A UIMA C++ test driver is available so that a UIMA C++ analytic can be developed and tested with
+standard native programming tools; no programing in Java is required.
+On the other hand, for a more consistent development environment
+Eclipse can provide a single IDE for both Java and C++ components
+using the <a href="http://www.eclipse.org/cdt/">CDT</a>.
+</p>
+<p>UIMA currently uses the JNI interface to move between Java and C++. Using the JNI, a C++ component
+can run in the same JVM process as other UIMA components written in Java. A UIMA C++ analytic can be run
+as a UIMA service, using the standard UIMA Java service wrapper. Future versions will provide a
+native C++ service wrapper.
+</p>
+
+<h3>1.1 UIMA C++ Functionality</h3>
+<p>The UIMA C++ framework implements a subset of that in Java. Major functionality consists of:
+<ol>
+<li>The ability to instantiate primitive or aggregate analysis engines.</li>
+<li>The UIMA context object for each analysis engine.</li>
+<li>Complete set of CAS APIs.</li>
+<li>CAS data serialization compatible with UIMA Java. XMI, XCAS and binary formats all supported.</li>
+<li>A JNI controller supporting direct integration with UIMA running on Java.</li>
+<li>Support for analytics written in Perl, Python and Tcl.</li>
+<li>A driver utility for native development and testing.</li>
+</ol>
+</p>
+<p>Major UIMA functionality missing in the C++ framework:
+<ol>
+<li>No native UIMA service wrapper; requires Java framework and JNI interface for C++ services.</li>
+<li>No custom flow controller for aggregates.</li>
+<li>No multithreaded application driver (e.g. the CPM).
+</ol>
+</p>
+
+<p>UIMA compliant annotators can be written in Perl, Python and Tcl using C++ annotators included in this package. For further details see <a href="../scriptators/perl/Perl.html">Perl</a>, <a href="../scriptators/python/Python.html">Python</a> and <a href="../scriptators/tcl/Tcl.html">Tcl</a>.
+</p>
+<p>The UIMA C++ framework depends on Unicode support from the ICU (see http://www.ibm.com/software/globalization/icu), XML parsing support from xerces (see http://xml.apache.org/xerces-c/) and platform portability from APR (see http://apr.apache.org/).
+</p>
+
+<p>API documentation for the C++ framework is available <a href="html/index.html">here</a>.
+</p>
+
+<h3>1.2 Supported Platforms</h3>
+<p>Linux® Intel® 32 and 64-bit platforms, MacOSX and Windows® 2000/XP.</p>
+
+<h3>1.3 Binary Distribution</h3>
+<p>Binary distributions are in compressed tarfiles for Linux and zipfiles for Windows.
+</p>
+
+<h3>1.4 Source Distribution</h3>
+The source code distributions are in a compressed tarfile for Unix builds and a zipfile for Windows builds.
+
+<h2>2.0 Installing and Testing UIMA C++</h2>
+The binary distribution can be installed anywhere. However, when
+installed on a system with the Apache UIMA Java distribution, unpacking directly underneath $UIMA_HOME
+provides better interoperability.
+
+<h3>2.1 Setting Environment Variables</h3>
+<p>Set UIMACPP_HOME to the installed location of the UIMA C++ SDK.</p>
+<p>
+Both the UIMA C++ framework and the users' C++ components are implemented as
+shared libraries and must be available to the native library loader.
+On Linux these directories must be in the LD_LIBRARY_PATH, in DYLD_LIBRARY_PATH on MacOSX
+and on Windows in the system PATH. The UIMA C++ test driver should be added to the system PATH.
+</p>
+<h4>On Linux</h4>
+ <ul>
+ <code>export LD_LIBRARY_PATH=$UIMACPP_HOME/lib:$LD_LIBRARY_PATH</code><br>
+ <code>export PATH=$UIMACPP_HOME/bin:$PATH</code>
+ </ul>
+<h4>On Windows</h4>
+ <ul>
+ <code>set PATH=%UIMACPP_HOME%\bin;%PATH%</code>
+ </ul>
+
+<h3>2.2 Verifying Your Installation</h3>
+
+<p>To test the installation, set the environment variables as described above
+and follow these directions:
+
+<h4>2.2.1 On Linux</h4>
+ <ul>
+ <code>
+ cd $UIMACPP_HOME/examples<br>
+ make -C src -f DaveDetector.mak
+ </code>
+ </ul>
+<p>The build should create a shared library, DaveDetector.so, which must be placed
+ in the LD_LIBRARY_PATH.<br>
+</p>
+<ul>
+ <code>
+ LD_LIBRARY_PATH=`pwd`/src:$LD_LIBRARY_PATH<br>
+ </code>
+</ul>
+Run this C++ annotator as follows:
+ <ul>
+ <code>runAECpp descriptors/DaveDetector.xml data/example.txt</code>
+ </ul>
+<p>
+The runAECpp driver will process the input text file and DaveDetector should find a Dave in it.
+</p>
+
+<h4>2.2.2 On Windows</h4>
+ <ul>
+ <code>
+ cd %UIMACPP_HOME%\examples<br>
+ devenv src\DaveDetector.vcproj /build release<br>
+ </code>
+ </ul>
+<p>The build should create a shared library, DaveDetector.dll, which must be
+placed in the PATH.<br>
+</p>
+<ul>
+ <code>
+ PATH=%CD%\src;$PATH
+ </code>
+</ul>
+Run this C++ annotator as follows:
+ <ul>
+ <code>runAECpp descriptors\DaveDetector.xml data\examples.txt </code>
+ </ul>
+<p>
+The runAECpp driver will process the input text file and DaveDetector should find a Dave in it.
+</p>
+<h4>2.2.3 More Info on UIMA C++ Examples</h4>
+<p>For further details about how to build and run other examples see
+<a href="../examples/readme.html">C++ Examples</a>
+</p>
+
+<h3>2.3 Testing Interoperability with Java</h3>
+To test the interoperability with UIMA Java SDK, make sure UIMA_HOME is set to the location of the UIMA SDK, and that its bin directory is in the PATH. Run DaveDetector as follows:
+<h4>2.3.1 On Linux</h4>
+<ul>
+ <code>runTAE.sh descriptors/DaveDetector.xml data</code>
+</ul>
+<h4>2.3.2 On Windows</h4>
+<ul>
+ <code>runTAE descriptors\DaveDetector.xml data</code>
+</ul>
+The runTAE driver will process all files in the data directory and DaveDetector should find Daves in some of them.
+
+<h2>3.0 Developing a C++ Component</h2>
+
+<h3>3.1 Developing UIMA C++ Components without Java</h3>
+<p>
+It is advantageous to debug C++ components as stand-alone C++ applications.
+The program <CODE>runAECpp</CODE> found under the $UIMACPP_HOME/bin directory is a
+C++ utility that imports one or more XML format CAS files into CAS objects and for each calls the
+<CODE>process</CODE> method of the specified UIMA C++ component, optionally
+saving the results as XML format CAS files.
+</p>
+<p>
+Both XMI and XCAS format CAS files are supported by runAECpp.
+The <CODE>XmiWriterCasConsumer</CODE> and <CODE>XCasWriterCasConsumer</CODE> are Java UIMA components
+that can be run at any point
+in the CPE flow to export the contents of the CAS object to a file in an XML format.
+</p>
+<p>
+To debug using XML CAS serialization, use one of the above serializers to dump
+the CAS at the point the C++ component would be called,
+or even create the XML content with an editor. Use runAECpp to process XML format CAS input as follows:
+</p>
+<ul>
+<code>runAECpp <UimaCppDescriptor> <InputFileOrDirectory> [<OutputDirectory>] [-x | -xmi] [-s ViewName] [-l loglevel]</code>
+</ul>
+<ul>
+<li>UimaCppDescriptor is the C++ component descriptor</li>
+<li>InputFileOrDirectory is the name of an input file or a directory containing input files</li>
+<li>If an optional OutputDirectory is specified, the contents of the CAS after processing will be written out with the same names as the input files. Be careful not to specify the directory containing the input files!</li>
+<li>Use the -x option if the input file(s) are in XCAS format. Use the -xmi option to process XMI format CAS input. Otherwise, input files are assumed to be text files and are used to create the document text for analysis.</li>
+<li>To support multi-View scenarios where the C++ component is expecting a view of a specific Sofa, the name of the view to use can be provided</li>
+<li>The loglevel for messages can be specified</li>
+</ul>
+<p>Sample XMI and XCAS format CAS files are included with the UIMA C++ examples. After building the
+<CODE>SofaExampleAnnotator</CODE> example as described above for DaveDetector, try:</p>
+<ul>
+<code>
+runAECpp -xmi descriptors/DaveDetector.xml data/tcas.xmi <yourOutputDir><br>
+runAECpp -xmi descriptors/DaveDetector.xml data/sofa.xmi <yourOutputDir> -s EnglishDocument<br>
+runAECpp -x descriptors/SofaExampleAnnotator.xml data/sofa.xcas <yourOutputDir><br>
+</code>
+</ul>
+<p>For further details about these and other examples see
+<a href="../examples/readme.html">C++ Examples</a>
+</p>
+
+<h3>3.2 Message Logging from a C++ Component</h3>
+<p>For formal integration with UIMA applications, a logfile interface is available.
+When a C++ annotator is called from Java, logging messages are integrated into the Java log.
+If the C++ annotator is called from a native C++ application, such as runAECpp,
+a local logfile may be created. The name of the logfile is taken from the
+the environmental parameter, UIMACPP_LOG_FILE, and it is opened "append".
+The default is to disable logging.
+</p>
+<p>Three levels of message logging can be used: Message, Warning and Error.
+When called from Java the UIMA log level is used to control output.
+When called from a C++ application an API is available to set the log level; the default level is Error.
+When called from runAECpp the value of these levels are 0, 1, and 2, respectively.
+</p>
+</body>
+</html>
Modified: incubator/uima/uimacpp/trunk/examples/readme.html
URL: http://svn.apache.org/viewvc/incubator/uima/uimacpp/trunk/examples/readme.html?view=diff&rev=531960&r1=531959&r2=531960
==============================================================================
--- incubator/uima/uimacpp/trunk/examples/readme.html (original)
+++ incubator/uima/uimacpp/trunk/examples/readme.html Tue Apr 24 07:40:14 2007
@@ -11,16 +11,11 @@
This directory contains example code that illustrate how to use the UIMA C++ Framework.
</p>
<h2>Building the Examples</h2>
-Copy the examples directory and its subdirectories into a writable directory, referred to here as myExamples, and cd to myExamples. Set environment variables and build the examples as follows:
+Set environment variables as described in the overview and build the examples as follows:
<h3>On Linux</h3>
-Assuming the SDK was unpacked in your home directory:
<ul>
<code>
- export UIMACPP_HOME=$HOME/uimacpp<br>
- export LD_LIBRARY_PATH=$UIMACPP_HOME/lib:$LD_LIBRARY_PATH<br>
- export PATH=$UIMACPP_HOME/bin:$PATH<br>
- cp -r $UIMACPP_HOME/examples myExamples<br>
- cd myExamples<br>
+ cd $UIMACPP_HOME/examples<br>
make -C src -f all.mak
</code>
</ul>
@@ -33,14 +28,10 @@
</ul>
<h3>On Windows</h3>
-Assuming the zipfile was installed in C:\UIMA
<ul>
<code>
- set UIMACPP_HOME=c:\UIMA\uimacpp<br>
- set PATH=%UIMACPP_HOME%\bin;%UIMACPP_HOME%\lib;%PATH%<br>
- xcopy /SYQI %UIMACPP_HOME%\docs\examples c:\myExamples<br>
- cd c:\myExamples<br>
- devenv src\uimacpp-examples.sln /build debug<br>
+ cd %UIMACPP_HOME%\examples<br>
+ devenv src\uimacpp-examples.sln /build release<br>
</code>
</ul>
This will create DLLs and executables in the src directory which must be placed in the PATH as follows:
@@ -50,7 +41,7 @@
</code>
</ul>
<h2>Running the Sample UIMA Components</h2>
-<p> Build the examples and set up environment variables as described above. These components can be run using either in the native C++ environment using the <code>runAECpp</code> program or run from Java using the <code>runTAE</code> utility or integrated into a CPE. The UIMA C++ descriptors are location in the descriptors subdirectory.
+<p>These components can be run using either in the native C++ environment using the <code>runAECpp</code> program or run from Java using the <code>runAE</code> utility or integrated into a CPE. The UIMA C++ descriptors are location in the descriptors subdirectory.
<h3>DaveDetector</h3>
A UIMA annotator that finds Daves in text and annotates them. It has one configuration parameter, <code>DaveString</code>, that specifies the string to match. It illustrates how to use the CAS APIs to create annotations and add them to the index.
<p>
Modified: incubator/uima/uimacpp/trunk/scriptators/perl/Perl.html
URL: http://svn.apache.org/viewvc/incubator/uima/uimacpp/trunk/scriptators/perl/Perl.html?view=diff&rev=531960&r1=531959&r2=531960
==============================================================================
--- incubator/uima/uimacpp/trunk/scriptators/perl/Perl.html (original)
+++ incubator/uima/uimacpp/trunk/scriptators/perl/Perl.html Tue Apr 24 07:40:14 2007
@@ -29,12 +29,12 @@
<h2>Supported Platforms</h2>
<p>The Perltator has been tested with PERL version 5.8 on Linux and with ActivePerl-5.8.8.816-MSWin32-x86-255195.msi on Windows XP.
</p>
-<p>UIMA C++ now uses Apache APR as the platform portability library. There is an incompatibility between APR and ActivePerl typedefs which must be resolved by editing the ActivePerl header win32.h. Change uid_t and gid_t from "long" to "int".
+<p>UIMA C++ uses Apache APR as the platform portability library. There is an incompatibility between APR and ActivePerl typedefs which must be resolved by editing the ActivePerl header win32.h. Change uid_t and gid_t from "long" to "int".
</p>
<h2>Prerequisites</h2>
<p>The Perltator uses SWIG (http://www.swig.org/) to implement the PERL library interface to UIMA. SWIG version 1.3.29 or later is required.</p>
-<p>The UIMA C++ Enablement layer is required. This Perltator has been tested with uimacpp version 1.4.4.
+<p>The UIMA C++ Enablement layer is required.
</p>
<h2>Perltator Distribution</h2>
Modified: incubator/uima/uimacpp/trunk/scriptators/python/Python.html
URL: http://svn.apache.org/viewvc/incubator/uima/uimacpp/trunk/scriptators/python/Python.html?view=diff&rev=531960&r1=531959&r2=531960
==============================================================================
--- incubator/uima/uimacpp/trunk/scriptators/python/Python.html (original)
+++ incubator/uima/uimacpp/trunk/scriptators/python/Python.html Tue Apr 24 07:40:14 2007
@@ -32,7 +32,7 @@
<h2>Prerequisites</h2>
<p>The Pythonnator uses SWIG (http://www.swig.org/) to implement the Python library interface to UIMA. SWIG version 1.3.29 or later is required.</p>
-<p>The UIMA C++ Enable layer is required. This Pythonnator has been tested with uimacpp version 1.4.4.
+<p>The UIMA C++ Enable layer is required.
</p>
<p>In addition to the Python interpreter, a Python development package (python-devel on Linux) is required for building the Pythonnator. The above mentioned Windows version includes a development package.</p>
Modified: incubator/uima/uimacpp/trunk/scriptators/tcl/Tcl.html
URL: http://svn.apache.org/viewvc/incubator/uima/uimacpp/trunk/scriptators/tcl/Tcl.html?view=diff&rev=531960&r1=531959&r2=531960
==============================================================================
--- incubator/uima/uimacpp/trunk/scriptators/tcl/Tcl.html (original)
+++ incubator/uima/uimacpp/trunk/scriptators/tcl/Tcl.html Tue Apr 24 07:40:14 2007
@@ -32,7 +32,7 @@
<h2>Prerequisites</h2>
<p>The Tclator uses SWIG (http://www.swig.org/) to implement the Tcl library interface to UIMA. SWIG version 1.3.29 or later is required.</p>
-<p>The UIMA C++ Enablement layer is required. This Tclator has been tested with uimacpp version 1.4.4.
+<p>The UIMA C++ Enablement layer is required.
</p>
<h2>Tclator Distribution</h2>