UIMA project logo
Creating Distributions - version 2.3.0 and earlier
Apache UIMA

Search the site

 Building Apache UIMA distributions for release 2.3.0 and earlier

This page describes how we build distributions for the 2.3.0 and earlier releases. See this page for information on building distributions for the 2.3.1 and later releases.

NOTE: Build distributions using the lowest version number of Java supported (currently Java 5), to insure no methods only available with higher Java levels are referenced.

This is because specifying source and target of, say, Java 1.5, and then accidentally using a Java 6 library method, surprisingly doesn't cause a mvn driven compile failure (if Maven is running under Java 6).

 Building the Apache UIMA base distribution

These instructions are for the 2.3.0 release; the build process is being revised for 2.3.1, and these pages will be updated as that is completed.

Start by extracting and building the code manually as described on the source code page. Once you have all that working, you can build a distribution with the help of the scripts in uimaj-distr/src/main/build. Start out in an empty directory and run:

extractAndBuild.bat from the uimaj-distr/src/main/build directory.
This will extract the source code from SVN, compile and run the tests, and finally build the distribution artifacts. (It will not build the Eclipse Update Site).

Note: to get the PDFs built, you have to run this on a Windows machine.

The build process for base UIMA builds individual Jar files suitable for uploading into a maven repository, and 2 assemblies (one for the source and one for the binary distributions). The individual Jar files are in the target directories of the individual projects they belong to. The assemblies (source and binary) are in the uimaj-distr/target directory.

 Building the Apache UIMA-AS distribution

The build process for UIMA-AS is similar. You can use the extractAndBuild script from the distribution directories: uima-as-distr/src/main/build for UIMA-AS

 Building Apache UIMA Sandbox distributions

To build the Sandbox AnnotatorPackage distribution, you need a working Maven development environment as for example set up for UIMA core. With the help of the scripts in SandboxDistr/annotator-package/build you can create your own distribution. Start out in an empty directory and run:

extractAndBuild.bat <tag name>

This will extract the source code with the specified tag name from the SVN, compile and run the tests, and finally build the distribution artifacts.

 Building the Eclipse Update Site

The Eclipse update site build is somewhat unusual, because it accumulates releases over time from various UIMA distributions. This is because we have just one update site (at the moment) for all releases, for all components that want this service, such as the core UIMA and UIMA-AS.

The Eclipse plugs are organized into Features. These each have a project, using the naming convention of uimaj-eclipse-feature-xxxx. Currently we have 3 features:

  • uimaj-eclipse-feature-deployeditor (for the UIMA-AS editor for deployment descriptors)
  • uimaj-eclipse-feature-runtime (for other plugins, and for building RCP applications)
  • uimaj-eclipse-feature-tools (holds most of the UIMA Eclipse tooling

Prior to building the update site, the feature sites need to be updated to reflect the set of features for the current release. The build will create Jar files tagged with the release number, for each updated feature.

The Eclipse update site is built in 2 phases.

  1. The first phase occurs during the normal maven builds of the project - this phase builds the Jars that constitute the plugins.

  2. The second consists of several parts.

    The set of feature projects, uimaj-eclipse-feature-xxxxx, must all be updated for the current release. Generally, only the pom.xml and feature.xml files will need updating.

    Update the uimaj-eclipse-update-site project for the release: the files pom.xml and site.xml. Then execute the maven command mvn install on the uimaj-eclipse-update-site project. The POM for this is an aggregator POM and will recursively invoke install on the uimaj-eclipse-feature-xxxxx projects, to build their Jars.

    The result of running mvn install will be a partial, but working Eclipse update site, located in the project's target/eclipse-update-site directory. It is partial, because the real update site keeps back level versions of the feature and plugin jars, while this site will only have jars for the current release. When uploading to the distribution point after the release is approved, be sure to merge in those jars. The feature Jars (in the uimaj-eclipse-update-site/features directory) for the new update site are checked into SVN, for use by future builds.

Building the Eclipse Update Site 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

 Signing a distribution

If you're not set up for creating PGP signatures, the first section tells you where to get the necessary software, how to create a personal key and how to upload it to a key server. If you're already set up with GnuPG or equivalent software, you can skip right to the next section.

Getting started with release signing

Although you can follow the steps described here mechanically, it is preferable to have at least a basic understanding of what it actually is you are doing. Here is a good introduction to PGP and digital certificates. We recommend reading this document front-to-back. There is also more general information on signing Apache releases. More information is also available on the wiki. Some of that information is outdated, though, so take with a grain of salt. The UIMA release signing script is based on the code from the wiki page.

Start by downloading GnuPG. For the purposes of release signing, it is sufficient to install the command line tools. After installing GnuPG, create a public/private key pair with

gpg --gen-key
This is pretty self-explanatory, some more information is in the release signing FAQ. It is vital that you remember the passphrase you choose when creating the key; you will need it later for using your private key to sign the release.

You can now list your public key with the following command:

gpg --armor --export
The output will look like this:
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.6 (MingW32)

mQGiBEWszKIRBACRscWnk1F408lWIZEgqx6OffiMtgApEVdl9UXXF2+DeS5WrHj0
1KDm9Q5Ir/o3f1qw7Il16Z496nDqmZHFKcrIgZvXcp5oCRE8sPMwdoy6X9kqVKug
...
-----END PGP PUBLIC KEY BLOCK-----
There are two places this output needs to go: the UIMA KEYS file, and a public key server.
  1. Append your key (delimiting lines and all) to uima-website/docs/KEYS. You can optionally place your name above the key, but that is for documentation purposes only. Don't forget to commit the KEYS file to SVN.
  2. Upload your public key to the MIT public key server and any other key server you think is appropriate (follow instructions on website).
Your public key can later be used by our users to verify releases that you signed.

You're now set up to do the actual release signing, and we'll tell you how in the next section.

Signing a Apache UIMA Release

You can use the script uimaj-distr/src/main/build/signRelease.sh to do the actual release signing. The script generates a PGP ASCII-armored detached signature file for each release artifact. This is a hash/message digest encrypted by your private key. The user can later use your public key to decrypt the message digest, which in turn is used to verify that the corresponding release artifact has not been altered. Sounds complicated, but is simple in practice.

To use the signRelease script, cd to uimaj-distr project, and issue the command:

src/main/build/signRelease.sh <version> <passphrase>
For example: src/main/build/signRelease.sh uimaj-2.3.0-incubating "Your passphrase in quotes" Note that the passphrase needs quotes if it contains blanks or special characters.

This script will sign the binary and source release artifacts, as well as the Jars and pack.gz (packed Jar format) that are generated for the Eclipse update site.

Signing a Sandbox AnnotatorPackage Release

You can use the script SandboxDistr/annotator-package/build/signRelease.sh to do the actual release signing. The script generates a PGP ASCII-armored detached signature file for each release artifact. This is a hash/message digest encrypted by your private key. The user can later use your public key to decrypt the message digest, which in turn is used to verify that the corresponding release artifact has not been altered. Sounds complicated, but is simple in practice.

To use the signRelease script, cd to SandboxDistr/annotator-package folder, and issue the command:

build/signRelease.sh <version> <passphrase>
For example: build/signRelease.sh uimaj-annotator-addons-2.2.2-incubating "passphrase in quotes"
Note that the passphrase needs quotes if it contains blanks or special characters.

This script will sign the binary and source release artifacts.

Signing an Eclipse update site

This is one step in the Release process for the Eclipse update site, and is described on the Doing a Release page.