Apache UIMA uses Maven 2 to do builds. Release 2.2.x of Maven, or later, is required. Download Maven from http://maven.apache.org and add <maven-home>/bin to your path.

The source can be obtain in two ways:

1. You can checkout the source from SVN, from trunk, or a particular tagged release, or
2. you can use the source version of the release artifact you download from the download page.

If you 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). Note that the PDF files only build correctly on a Windows platform (due to font issues).

Building from the command line

To build base UIMA from the command line, $> cd uimaj $> mvn install Builds for uima-as and the sandbox projects work similarly, however the build process requires that base UIMA be in the same containing directory. If you check out these other projects from SVN, you will need to copy the projects from these checkouts into the same base directory as base UIMA, so all the projects are siblings within that directory. The same is true for building from the source distribution. Once the directory is set up, do: $> cd uimaj-as $> mvn install or $> cd Sandbox $> 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 project for uimaj (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. 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, the details of the failures are logged in a file for each project which has a failue, in the folder target/surefire-reports. In Eclipse, you can use the Search facility to search Files in the workspace of type "*.txt" for the string "<<< FAILURE!" to locate all the failure messages. 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

Distributions include zip/tar packages of source or binaries. Please refer to this page: Building a distribution for details on how to do this. 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 install 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 and .tar.gz archives of the full UIMA distribution in the uimaj-distr/target directory. Similarly, for building the uima-as add-on distribution, first be sure you've built the projects themselves (see above) and then do: cd ..\uima-as-distr mvn install Similarly, for building the sandbox distribution, first be sure you've built the projects themselves (see above) and then do: cd annotator-package mvn install This maven command will create the assemblies in the target directory, and will also run the Release Audit Tool (RAT) on the result. To skip running RAT, use the command mvn package.

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.