Building UIMA distributions

Building the Apache UIMA core distribution

Building Apache UIMA Sandbox distributions

Building AnnotatorPackage distribution

Signing a distribution

Getting started with release signing

Signing a Apache UIMA Release

Signing Sandbox AnnotatorPackage Release

Building the Apache UIMA core distribution

To build a distribution, you will need to set up your Maven development environment as described on the source code page. Try extracting and building the code manually as described there. 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.sh
This will extract the source code from SVN, compile and run the tests, and finally build the distribution artifacts.

The build process builds individual Jar files suitable for uploading into a maven repository, 2 assemblies (one for the source and one for the binary distributions), and an Eclipse update site. 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.

Eclipse Update Site

The Eclipse update site build is somewhat unusual, because it accumulates releases over time from various UIMA projects. 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 (a sandbox project).

The Eclipse update site is built in 2 phases. The first phase occurs during the normal maven builds of the project - this phase builds the Jars that constitute the plugins.

The second phase occurs after a release is approved, and consists of several parts:

Any new Plugin Jars are packed

The feature jars are generated

The Site.xml is updated to include the any new components / versions

The site digest is regenerated

These steps are carried out by running the build.xml script with "ant" in the uimaj-eclipse-update-site project, after placing any new plugin jars from the approved release candidate in the "plugins" folder. The "plugins" folder should not have any other jars in it (other than the new ones which will be packed); the "features" folder is saved in SVN and accumulates the feature Jars for all the features/versions. The feature Jars do not actually contain any Java classes; the Jar format is just to consolidate and compress the file contents.

The result of running the build.xml is a partial eclipse update site in the uimaj-eclipse-update-site project, in the target/eclipse-update-site directory. It is partial because it doesn't contain all the plugin jars from previously released versions. The official distribution place for the update site on www.apache.org will be updated by adding any new plugin and feature jars, and replacing the site.xml and digest files, with the ones in the target/eclipse-update-site directory.

Building Apache UIMA Sandbox distributions

Building AnnotatorPackage distribution

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.sh <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.

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. Make sure to 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.

Append your key (delimiting lines and all) to uimaj-distr/src/main/readme/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.

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.2.2-incubating-SNAPSHOT "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.