Apache UIMA uses Maven 2 to do builds. Download Maven from http://maven.apache.org and add <maven-home>/bin to your path.

If you are building from a source distribution, and want to build the DocBooks from the Docbook sources, you need to set up your DocBook tooling by obtaining the needed parts, either from the UIMA SVN or from other places on the web (see below).

Building from the command line

$> cd uimaj $> mvn install The first time you try this, you will probably get an error that javax:activation:activation:jar:1.0.2 is not found. To resolve this, download activation.jar from http://java.sun.com/products/archive/javabeans/jaf102.html and execute the command: $> mvn install:install-file \ -DgroupId=javax.activation \ -DartifactId=activation \ -Dversion=1.0.2 \ -Dpackaging=jar \ -Dfile=/path/to/file/activation.jar then re-run the UIMA build with the command: $> mvn install This should build all of the jars and run the unit tests. Each jar will be located under the target subdirectory of its project, for example uimaj-core/target/uima-core.jar. If you want to build just one of the "projects", and not the whole thing, cd to the project you want to build, and run mvn install there.

Building from Eclipse

First, follow all the steps under "Building from the command line, above." You will only need to do this once. (Optional) If you want a new workspace for the maven work, start Eclipse and create a new workspace. In a command window, execute mvn -Declipse.workspace=<eclipse workspace dir> \ eclipse:add-maven-repo This adds a maven repository to your machine (On Windows, under documents & settings / .m2 / repository), and sets up an Eclipse Java Build Path variable to reference it. Use Eclipse's SVN Repository explorer to checkout all the projects under uimaj/trunk. Tell it to create new Java projects for these. cd uimaj to switch to the Eclipse workspace for the uimaj project itself is (it has the top level POM), and run the command: mvn eclipse:eclipse If you haven't run the "install" using maven (because you forgot to follow all the steps under "Building from the command line, above"), you should do the command mvn install eclipse:eclipse. The "install" argument builds UIMA using maven, before the eclipse:eclipse goal is run. This is needed for the Eclipse Plugins that are part of UIMA - these projects have their "MANIFEST.MF" file built by maven from the information in the maven POMs. This step may take a few minutes because the "install" lifecycle includes running the unit tests. If you notice error messages that components need to be downloaded from the maven repository, it might tell you to redo the command using the -DdownloadSources=true parameter in order to check remote repositories for sources. Return to Eclipse, and if needed, select all the projects and push F5 to "refresh" them (because the previous command changed the .project and .classpath files). You can set your workspace to automatically refresh - in which case skip this step. The projects should now compile without errors, and have build paths which reference copies of things in your local maven repository. You can run the unit tests in Eclipse by right-clicking on a folder (for example uimaj-core/src/test/java) and selecting Run As -> JUnit Test. This will run all tests under that folder.

What to do if the tests fail

(Note: this kludgy procedure needs improvement) If you get a failure messsage, in Eclipse, use the Search facility to search Files in the workspace of type "*.txt" for the string "<<< FAILURE!" If not using Eclipse, you can use grep to accomplish the same thing. You can bypass the tests by doing mvn -Dmaven.test.skip install. But please do this only after you've run without it and have verified the tests results.

How to build the full Apache UIMA distribution

Special setup to get around a Maven issue (March 2008) Building the distribution requires that Maven uses ant version 1.7.0, but the Maven antrun plugin is configured to use ant 1.6.5. As a work-around, until a version of this plugin supporting ant 1.7.0 is available, please update your local maven repository entry for the antrun plugin as follows: Locate the directory containing the antrun plugin's pom. On windows, it will be in C:\Documents and Settings\[user-name]\.m2\repository\org\apache\maven\plugins\maven-antrun-plugin\1.1. The file in this directory to modify is maven-antrun-plugin-1.1.pom. Find the two dependency sections that refer to ant 1.6.5. In each of these change 2 things: the <version>1.6.5</version> to <version>1.7.0</version>, and above this, the <groupId>ant</groupId> to <groupId>org.apache.ant</groupId> This will tell antrun to use ant 1.7.0. Building the distribution requires some additional maven setup: you have to have Eclipse version 3.3 or later installed, and you have to indicate to maven where it is installed. In the examples below, this is shown as c:/your/path/to/eclipse. Note that you can type the slashes '/' as backslashes '\' in Windows -- it doesn't matter (both work). The path should be to an directory (which, by default is often named "eclipse" but can be named anything) containing the eclipse executable, and the subdirectory folders for Eclipse such as "plugins" and "features". You can do this in one of 3 ways. The first way is to create a maven "settings.xml" file, and store it in your local maven repository, (for instance, on Windows, in the directory: Documents and Settings/[user-login]/.m2). This file is useful for other things as well, such as specifying upload servers. The file contents that you need to specify the Eclipse location looks like this: <settings xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation= "http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <profiles> <profile> <id>local-build-configuration</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <uima-maven-build-eclipse-home> c:/your/path/to/eclipse </uima-maven-build-eclipse-home> </properties> </profile> </profiles> <activeProfiles> <activeProfile> local-build-configuration </activeProfile> </activeProfiles> </settings> The second way to do this is to set an environment variable. Here's an example in Windows: set ECLIPSE_HOME=c:/your/path/to/eclipse The third way is to pass a command line argument to the maven command below, which looks like this: -Duima-maven-build-eclipse-home=c:/your/path/to/eclipse To build a distribution, first do a build as described in "Building from the command line". Then (assuming you set up the Eclipse path using one of the first 2 methods, execute the following: $>cd ../uimaj-distr $>mvn assembly:assembly This will build the javadocs and the manual (using docbooks, as described below), will create the Eclipse update site for the Eclipse plugins, and will create .zip, .tar.gz, and .tar.bz2 archives of the full UIMA distribution in the uimaj-distr/target directory.

Building uima-docbooks

The UIMA Source distribution includes the uima-docbook-tool project, which is the tooling needed to build the Docbooks; the actual Docbook sources are in the uima-docbooks project, in the src directory. The DocBook tooling requires several components that are not included in the source distribution, but instead are automatically downloaded from the internet the first time you run the tools; you will be asked to accept the licenses for these components. Please read the README.FIRST and README files in the uima-docbook directory for important information about setting up the tooling. In particular, in order to get the images to be rendered in the PDF output, you must obtain the "Java Advanced Imaging" library from Sun. Note that the uima-docbooks project is not built using Maven; it is built by an ant script. If you want to build the documentation without building the entire UIMA distribution, cd to the uima-docbooks directory, and run ant. This will build all 4 books into the uima-docbooks/target directory. Note that each book is actually built twice - the first build only runs the transforms to get the links established and setup of cross reference database table. The second outputs the html and pdf files, using the cross reference database table just created.

Creating A4-size PDF documentation

If you don't live in the US, you may wish to create your PDF documentation in a different format, e.g., A4. To do this, edit the file uima-docbook-tool/properties/default.docbook.properties. It contains a line paper.type = Letter Change this setting to A4 and rebuild the documentation. Note: if you've previously built the documentation, you need to run ant clean first, as the build doesn't pick up on this change automatically.