Building Apache UIMA™ from sources

We use Maven, release 3.0 or later, for building. Most of us use Eclipse as the IDE for working with Java. Maven has a plugin for Eclipse, m2eclipse, that is useful in working with Maven from within Eclipse.

One time initial setup

SVN: Click here for the one-time SVN setup. Maven: Click here for the one-time Maven 3.0 setup. Eclipse: Click here for the one-time Eclipse setup. This is only needed if you are using Eclipse as your IDE.

Building UIMA - using the command line

SVN Checkout: If the project is a module of a multi-module project (e.g., uimaj), check out the SVN directory containing all of the modules for the multi-module project. For example, (Windows - UIMA-SDK): svn checkout https://svn.apache.org/repos/asf/uima/uimaj/trunk c:\myWorkingDirectoryForUimaj If you have tortoiseSVN windows shell extensions installed, you can use the repo-browser right-click menu option to do this. cd to c:\myWorkingDirectoryForUimaj\. mvn install This will build the project and install it to your local Maven repository. For multi-module projects, it will build all the submodules. However, it won't build the ...-source-release.zip of all the sources. To build this along with the rest of the build, include the parameter -Papache-release, like so: mvn install -Papache-release The build process builds all of the jars, any docbooks, runs the unit tests and other validity checks, and may build a multi-module binary assembly (varies according to each project). The output artifacts (Jars, html and pdf documents, etc.) are found in each module's "target" directory, and also are put into your local Maven repository. Docbook output is placed in each project's target/site/d directory. Multi-module builds create the build artifacts (including the binary assembly) in the target folder of their top level project.

Building using Eclipse, with the m2eclipse plugin

Checkout from SVN exactly as above, into some location. Then use Eclipse menu: File -> Import -> Maven -> Existing Maven projects to import the project or projects (for multi-module projects) into an Eclipse workspace and set them up for Maven building. To run Maven commands on a project from within Eclipse, select the project, right click, and pick Run as and then select mvn install (or other choice as you wish). Help! I'm getting compile errors (class not found) in Eclipse! If your Maven build generates sources (e.g., you have some XMLBeans defined), then after the initial import and project build, you'll need to use the m2eclipse command Update Project Configuration found on the Maven context menu obtained by right-clicking the project folder. This will add the generated classes to Eclipse's classpath. Within a project, 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.

Building uima-docbooks

Docbook processing is done normally as a part of regular maven building of projects which have Docbooks. The base uimaj projects have 4 docbooks, and there is an aggregate project which builds all 4 of these: aggregate-uimaj-docbooks. Docbooks are built by the normal maven lifecycle, in the prepare-package phase.

Creating A4-size PDF documentation

The PDF docbook generation defaults to a paper type of USletter. You may override this by specifying the Maven property "pdfPaperType". You may specify this on the command line as follows: mvn -DpdfPaperType=A4 package The allowed values for paper type in Docbook can be seen on this page: https://docbook.sourceforge.net/release/xsl/current/doc/fo/page.width.portrait.html.

What to do if the tests fail

(Note: this kludgy procedure needs improvement) If you get a failure message, the details of the failures are logged in a file for each project which has a failure, 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.