You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by sc...@apache.org on 2011/01/25 20:47:47 UTC
svn commit: r1063425 [1/2] - in /uima/site/trunk/uima-website: docs/ xdocs/
Author: schor
Date: Tue Jan 25 19:47:47 2011
New Revision: 1063425
URL: http://svn.apache.org/viewvc?rev=1063425&view=rev
Log:
no Jira, continue refining the instructions for releasing and/or creating a distribution; split into before 2.3.1 and after.
Added:
uima/site/trunk/uima-website/docs/distribution-before-2.3.1.html
uima/site/trunk/uima-website/xdocs/distribution-before-2.3.1.xml
Modified:
uima/site/trunk/uima-website/docs/distribution.html
uima/site/trunk/uima-website/docs/release-before-2.3.1.html
uima/site/trunk/uima-website/docs/release.html
uima/site/trunk/uima-website/xdocs/distribution.xml
uima/site/trunk/uima-website/xdocs/release-before-2.3.1.xml
uima/site/trunk/uima-website/xdocs/release.xml
Added: uima/site/trunk/uima-website/docs/distribution-before-2.3.1.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/distribution-before-2.3.1.html?rev=1063425&view=auto
==============================================================================
--- uima/site/trunk/uima-website/docs/distribution-before-2.3.1.html (added)
+++ uima/site/trunk/uima-website/docs/distribution-before-2.3.1.html Tue Jan 25 19:47:47 2011
@@ -0,0 +1,562 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+
+
+ <!-- ====================================================================== -->
+ <!-- GENERATED FILE, DO NOT EDIT, EDIT THE XML FILE IN xdocs INSTEAD! -->
+ <!-- ====================================================================== -->
+ <html>
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
+ <style type="text/css">@import "stylesheets/base.css";</style>
+ <meta name="author" value="Apache UIMA Documentation Team">
+ <meta name="email" value="dev@uima.apache.org">
+
+
+
+ <title>Apache UIMA - Creating Distributions - version 2.3.0 and earlier</title>
+ </head>
+
+ <body>
+ <div class="topLogos">
+ <table border="0" width="100%" cellspacing="0">
+ <!-- TOP IMAGE -->
+ <tr>
+ <td align='LEFT'>
+ <a href="index.html">
+ <img style="border: 1px solid black;" src="./images/UIMA_banner2tlp.png" alt="UIMA project logo" border="0"/>
+ </a>
+ </td>
+ <td align='CENTER'>
+ <div class="pageBanner">Creating Distributions - version 2.3.0 and earlier</div>
+ </td>
+ <td align='RIGHT'>
+ <a href="http://www.apache.org">
+ <img src="./images/asf-logo-on-white-small.png" alt="Apache UIMA" border="0"/>
+ </a>
+ </td>
+ </tr>
+ </table>
+ <hr noshade="" size="1"/>
+ </div>
+ <table border="0" width="100%" cellspacing="4">
+ <tr>
+ <td align='RIGHT' colspan="2">
+ <form method="get" action="http://www.google.com/search">
+ Search the site
+ <input type="text" name="q" size="25" maxlength="255" value="" />
+ <input type="hidden" name="sitesearch" value="http://uima.apache.org/" />
+ <input name="Search" value="Search Site" type="submit"/>
+ </form>
+ </td>
+ </tr>
+ <tr> <!-- LEFT SIDE NAVIGATION -->
+ <td width="20%" valign="top">
+
+
+
+
+
+
+ <!-- regular menu -->
+ <div class="navBar">
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">General</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./index.html">Home</a>
+ </div>
+ <div class="navBarItem"> <a href="./downloads.cgi">Downloads</a>
+ </div>
+ <div class="navBarItem"> <a href="./documentation.html">Documentation</a>
+ </div>
+ <div class="navBarItem"> <a href="./news.html">News</a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="./mail-lists.html">Mailing Lists</a>
+ </div>
+ <div class="navBarItem"> <a href="./mail-lists.html#Apache_UIMA_Forums">Forums</a>
+ <a href="http://news.gmane.org/gmane.comp.apache.uima.general" target="_blank"><em> Users</em> <img src="images/offsitelink.png" /></a>
+ <a href="http://news.gmane.org/gmane.comp.apache.uima.devel" target="_blank"><em>Dev</em> <img src="images/offsitelink.png" /></a>
+ </div>
+ <div class="navBarItem"> <a href="http://cwiki.apache.org/UIMA/powered-by-apache-uima.html" target="_blank">Powered By UIMA <img src="images/offsitelink.png"</a>
+ </div>
+ <br style="line-height: .5em"/>
+ <div class="navBarItem"> <a href="http://issues.apache.org/jira/browse/uima" target="_blank">Issue tracker <img src="images/offsitelink.png"</a>
+ </div>
+ <div class="navBarItem"> <a href="http://cwiki.apache.org/UIMA/" target="_blank">Wiki <img src="images/offsitelink.png"</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Components & Tools</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./annotators.html">Annotators</a>
+ </div>
+ <div class="navBarItem"> <a href="./toolsServers.html">Tools & Servers</a>
+ </div>
+ <div class="navBarItem"> <a href="./sandbox.html">Sandbox</a>
+ </div>
+ <div class="navBarItem"> <a href="./external-resources.html">External Resources</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Community</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./get-involved.html">Get Involved</a>
+ </div>
+ <div class="navBarItem"> <a href="./contribution-policy.html">Contribution Policies</a>
+ </div>
+ <div class="navBarItem"> <a href="./faq.html">FAQ</a>
+ </div>
+ <div class="navBarItem"> <a href="./project-guidelines.html">Project Guidelines</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Development</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./dev-quick.html">Quick Start: building</a>
+ </div>
+ <div class="navBarItem"> <a href="./building-uima.html">Building from Source</a>
+ </div>
+ <div class="navBarItem"> <a href="./one-time-setup.html">One-time setups</a>
+ </div>
+ <div class="navBarItem"> <a href="./svn.html">Source Code</a>
+ </div>
+ <div class="navBarItem"> <a href="./distribution.html">Creating a Distribution</a>
+ </div>
+ <div class="navBarItem"> <a href="./release.html">Doing a UIMA release</a>
+ </div>
+ <div class="navBarItem"> <a href="./codeConventions.html">Code Conventions</a>
+ </div>
+ <div class="navBarItem"> <a href="./uima-specification.html">UIMA Specification (OASIS)</a>
+ </div>
+ <div class="navBarItem"> <a href="./team-list.html">Project Team</a>
+ </div>
+ <div class="navBarItem"> <a href="./maven-design.html">Maven Use</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">Events and Conferences</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="./iks09.html">IKS 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./gscl09.html">GSCL 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lsm09.html">LSM 2009</a>
+ </div>
+ <div class="navBarItem"> <a href="./lrec08.html">LREC 2008</a>
+ </div>
+ <div class="navBarItem"> <a href="./gldv07.html">GLDV 2007</a>
+ </div>
+ </div>
+ <br/>
+ <div class="navBarItem"> <div class="navPartHeading">ASF</div>
+ </div>
+ <div class="navBar">
+ <div class="navBarItem"> <a href="http://www.apache.org/licenses/" target="_blank">License <img src="images/offsitelink.png"</a>
+ </div>
+ <div class="navBarItem"> <a href="http://apache.org/foundataion/thanks.html" target="_blank">ASF Sponsors <img src="images/offsitelink.png"</a>
+ </div>
+ <div class="navBarItem"> <a href="http://www.apache.org/foundation/sponsorship.html" target="_blank">ASF Sponsorship <img src="images/offsitelink.png"</a>
+ </div>
+ <div class="navBarItem"> <a href="http://www.apache.org/foundation/thanks.html" target="_blank">Thanks <img src="images/offsitelink.png"</a>
+ </div>
+ <div class="navBarItem"> <a href="http://www.apache.org/security" target="_blank">Security <img src="images/offsitelink.png"</a>
+ </div>
+ </div>
+ </div>
+ </td>
+ <td width="80%" align="left" valign="top">
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Building Apache UIMA distributions for release 2.3.0 and earlier"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building Apache UIMA distributions for release 2.3.0 and earlier</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p style="font-size:125%">
+ This page describes how we build distributions for the 2.3.0 and earlier releases.
+ See <a href="distribution.html">this page</a> for information on
+ building distributions for the 2.3.1 and later releases.
+ </p>
+ <h4>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.</h4>
+ <p>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).</p>
+ <p>
+ <ul>
+ <li><a href="#Building the Apache UIMA base distribution">Building the Apache UIMA base distribution</a></li>
+ <li><a href="#Building the Apache UIMA-AS distribution">Building the Apache UIMA-AS distribution</a></li>
+ <li><a href="#Building Apache UIMA Sandbox distributions">Building Apache UIMA Sandbox distributions</a></li>
+ <li><a href="#Building the Eclipse Update Site">Building the Eclipse Update Site</a></li>
+ <li><a href="#Signing a distribution">Signing a distribution</a>
+ <ul>
+ <li><a href="#Getting started with release signing">Getting started with release signing</a></li>
+ <li><a href="#Signing a Apache UIMA Release">Signing a Apache UIMA Release</a></li>
+ <li><a href="#Signing Sandbox AnnotatorPackage Release">Signing Sandbox AnnotatorPackage Release</a></li>
+ </ul>
+ </li>
+ </ul>
+</p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Building the Apache UIMA base distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building the Apache UIMA base distribution</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p class="note">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.</p>
+ <p>
+ Start by extracting and building the code manually as described on the
+ <a href="./svn.html">source code page</a>.
+ Once you have all that working, you can build a distribution with the help
+ of the scripts in <code>uimaj-distr/src/main/build</code>. Start out in an empty directory and
+ run: <blockquote> <code>extractAndBuild.bat</code>
+ from the uimaj-distr/src/main/build directory.</blockquote>
+ This will extract the source code from SVN, compile and run the tests, and finally build the
+ distribution artifacts. (It will not build the
+ <a href="#Building the Eclipse Update Site">Eclipse Update Site</a>).
+ </p>
+ <p>Note: to get the PDFs built, you have to run this on a Windows machine.</p>
+ <p>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 <code>target</code> directories of the individual projects they
+ belong to. The assemblies (source and binary) are in the <code>uimaj-distr/target</code> directory.
+ </p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Building the Apache UIMA-AS distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building the Apache UIMA-AS distribution</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>
+ 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
+ </p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Building Apache UIMA Sandbox distributions"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building Apache UIMA Sandbox distributions</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>
+ 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 <code>SandboxDistr/annotator-package/build</code> you can create your own distribution.
+ Start out in an empty directory and run: </p>
+ <blockquote> <code>extractAndBuild.bat <tag name></code> </blockquote>
+ <p>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.
+ </p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Building the Eclipse Update Site"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building the Eclipse Update Site</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>
+ 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.
+ </p>
+ <p>
+ 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:
+ <ul>
+ <li>uimaj-eclipse-feature-deployeditor (for the UIMA-AS editor for deployment descriptors)</li>
+ <li>uimaj-eclipse-feature-runtime (for other plugins, and for building RCP applications)</li>
+ <li>uimaj-eclipse-feature-tools (holds most of the UIMA Eclipse tooling</li>
+ </ul>
+ </p>
+ <p>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.</p>
+ <p>
+ The Eclipse update site is built in 2 phases.
+ <ol>
+ <li>
+ <p>The first phase occurs during the normal maven
+ builds of the project - this phase builds the Jars that constitute the plugins.</p>
+ </li>
+ <li>
+ <p>
+ The second consists of several parts.
+ </p>
+ <p>The set of feature projects, uimaj-eclipse-feature-xxxxx, must all be updated for
+ the current release. Generally, only the <code>pom.xml</code> and <code>feature.xml</code> files will
+ need updating.</p>
+ <p>Update the uimaj-eclipse-update-site project for the release: the files <code>pom.xml</code>
+ and <code>site.xml</code>. Then execute the maven command
+ <code>mvn install</code> on the uimaj-eclipse-update-site project.
+ The POM for this is an aggregator POM and will recursively invoke <code>install</code> on the uimaj-eclipse-feature-xxxxx
+ projects, to build their Jars.</p>
+
+ <p>The result of running <code>mvn install</code> 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.</p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ 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".
+ </p>
+ <p>
+ You can do this in one of 3 ways.
+ </p>
+ <p>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:
+</p>
+ <pre>
+<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>
+ </pre>
+ <p>The second way to do this is to set an environment variable. Here's an example in Windows:</p>
+ <longquote><code>set ECLIPSE_HOME=c:/your/path/to/eclipse</code></longquote>
+ <p>The third way is to pass a command line argument to the maven command below, which looks like this:</p>
+ <longquote><code>-Duima-maven-build-eclipse-home=c:/your/path/to/eclipse</code></longquote>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Signing a distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Signing a distribution</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>
+ 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.
+ </p>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Getting started with release signing">
+ <h2>Getting started with release signing
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+ 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 <a href="http://www.pgpi.org/doc/pgpintro/">
+ good introduction to PGP</a> and digital certificates. We recommend reading this document front-to-back.
+ There is also more general information on <a href="http://www.apache.org/dev/release-signing.html">
+ signing Apache releases</a>. More information is also available <a href="http://wiki.apache.org/incubator/SigningReleases">
+ on the wiki</a>. 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.
+ </p>
+ <p>
+ Start by <a href="http://www.gnupg.org/download/">downloading GnuPG</a>. 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 <blockquote><code>gpg --gen-key</code></blockquote>
+ This is pretty self-explanatory,
+ some more information is <a href="http://www.apache.org/dev/release-signing.html#generate">in the
+ release signing FAQ</a>. 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.
+ </p>
+ <p>
+ You can now list your public key with the following command:
+ <blockquote><code>gpg --armor --export</code></blockquote>
+ The output will look like this:<blockquote>
+ <code>
+-----BEGIN PGP PUBLIC KEY BLOCK-----<br />
+Version: GnuPG v1.4.6 (MingW32)<br />
+<br />
+mQGiBEWszKIRBACRscWnk1F408lWIZEgqx6OffiMtgApEVdl9UXXF2+DeS5WrHj0<br />
+1KDm9Q5Ir/o3f1qw7Il16Z496nDqmZHFKcrIgZvXcp5oCRE8sPMwdoy6X9kqVKug<br />
+...<br />
+-----END PGP PUBLIC KEY BLOCK-----
+ </code>
+ </blockquote>
+ There are two places this output needs to go: the UIMA KEYS file, and a public key server.
+ <ol>
+ <li>
+ Append your key (delimiting lines and all) to <code>uima-website/docs/KEYS</code>.
+ 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.
+ </li>
+ <li>
+ Upload your public key to <a href="http://pgp.mit.edu/">the MIT public key server</a> and any
+ other key server you think is appropriate (follow instructions on website).
+ </li>
+ </ol>
+ Your public key can later be used by our users to verify releases that you signed.
+ </p>
+ <p>
+ You're now set up to do the actual release signing, and we'll tell you how in the next section.
+ </p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Signing a Apache UIMA Release">
+ <h2>Signing a Apache UIMA Release
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+ You can use the script <code>uimaj-distr/src/main/build/signRelease.sh</code> 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. </p>
+ <p>To use the signRelease script, <code>cd</code> to <code>uimaj-distr</code> project, and
+ issue the command:
+ <blockquote><code>src/main/build/signRelease.sh <version> <passphrase></code></blockquote>
+ For example: <code>src/main/build/signRelease.sh uimaj-2.3.0-incubating "Your passphrase in quotes"</code>
+ Note that the passphrase needs quotes if it contains blanks or special characters.
+ </p>
+ <p>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.</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Signing a Sandbox AnnotatorPackage Release">
+ <h2>Signing a Sandbox AnnotatorPackage Release
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+ You can use the script <code>SandboxDistr/annotator-package/build/signRelease.sh</code> 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. </p>
+ <p>To use the signRelease script, <code>cd</code> to <code>SandboxDistr/annotator-package</code> folder, and
+ issue the command:
+ <blockquote><code>build/signRelease.sh <version> <passphrase></code></blockquote>
+ For example: <code>build/signRelease.sh uimaj-annotator-addons-2.2.2-incubating "passphrase in quotes"</code>
+ <br />
+ Note that the passphrase needs quotes if it contains blanks or special characters.
+ </p>
+ <p>This script will sign the binary and source release artifacts.</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
+ <a name="Signing an Eclipse update site">
+ <h2>Signing an Eclipse update site
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>This is one step in the Release process for the Eclipse update site, and is described on the
+ <a href="release.html#Publish The Release">Doing a Release</a> page.</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
+ </td>
+ </tr>
+ <!-- FOOTER -->
+ <tr><td colspan="2">
+ <hr noshade="" size="1"/>
+ </td></tr>
+ <tr><td colspan="2">
+ <table class="pageFooter">
+ <tr>
+ <td><a href="index.html">Home</a></td>
+ <td><a href="privacy-policy.html">Privacy Policy</a></td>
+ <td style="font-size:75%">
+ Copyright © 2006-2011, The Apache Software Foundation.<br/>
+ Apache UIMA, UIMA, the Apache UIMA logo and the Apache Feather logo are trademarks of The Apache Software Foundation.<br/>
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ </td>
+ <td><a href="mailto:dev@uima.apache.org">Contact us</a></td>
+ </tr>
+ </table>
+ </td></tr>
+ </table>
+ </body>
+ </html>
+
Modified: uima/site/trunk/uima-website/docs/distribution.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/distribution.html?rev=1063425&r1=1063424&r2=1063425&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/distribution.html (original)
+++ uima/site/trunk/uima-website/docs/distribution.html Tue Jan 25 19:47:47 2011
@@ -177,25 +177,22 @@
</td></tr>
<tr><td>
<blockquote class="sectionBody">
- <h4>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.</h4>
- <p>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).</p>
- <p>
- <ul>
- <li><a href="#Building the Apache UIMA base distribution">Building the Apache UIMA base distribution</a></li>
- <li><a href="#Building the Apache UIMA-AS distribution">Building the Apache UIMA-AS distribution</a></li>
- <li><a href="#Building Apache UIMA Sandbox distributions">Building Apache UIMA Sandbox distributions</a></li>
- <li><a href="#Building the Eclipse Update Site">Building the Eclipse Update Site</a></li>
- <li><a href="#Signing a distribution">Signing a distribution</a>
- <ul>
- <li><a href="#Getting started with release signing">Getting started with release signing</a></li>
- <li><a href="#Signing a Apache UIMA Release">Signing a Apache UIMA Release</a></li>
- <li><a href="#Signing Sandbox AnnotatorPackage Release">Signing Sandbox AnnotatorPackage Release</a></li>
- </ul>
- </li>
- </ul>
-</p>
+ <p style="font-size:125%">
+ This page describes how we build distributions for the 2.3.1 and later releases.
+ See <a href="distribution-before-2.3.1.html">this page</a> for information on
+ building distributions for the 2.3.0 and prior releases.
+ </p>
+ <p>Normally, distributions are built within the release activity; the documentation for
+ that is <a href="release.html">here</a>, and includes information on how to build and update
+ the Eclipse update site, used for making our Eclipse plugins installable over the web.
+ This page focuses on building distributions outside of a release.</p>
+ <p>Do the <a href="one-time-setup.html">one-time-setup</a>
+ and the <a href="one-time-release-setup.html">extra setup for GPG signing</a>
+ if you haven't already done this.
+ The extra setup page also includes information on setting up for uploading (deploying) to
+ apache infrastructure - you can skip that if you are not planning on doing that. It also includes
+ information on setting some properties related to Eclipse - these are only needed for building the
+ Eclipse update site.</p>
</blockquote>
</p>
</td></tr>
@@ -203,30 +200,30 @@
<div class="sectionTable">
<table class="sectionTable">
<tr><td>
- <a name="Building the Apache UIMA base distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building the Apache UIMA base distribution</h1></a>
+ <a name="Building the Apache UIMA Java SDK distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building the Apache UIMA Java SDK distribution</h1></a>
</td></tr>
<tr><td>
<blockquote class="sectionBody">
- <p class="note">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.</p>
- <p>
- Start by extracting and building the code manually as described on the
- <a href="./svn.html">source code page</a>.
- Once you have all that working, you can build a distribution with the help
- of the scripts in <code>uimaj-distr/src/main/build</code>. Start out in an empty directory and
- run: <blockquote> <code>extractAndBuild.bat</code>
- from the uimaj-distr/src/main/build directory.</blockquote>
- This will extract the source code from SVN, compile and run the tests, and finally build the
- distribution artifacts. (It will not build the
- <a href="#Building the Eclipse Update Site">Eclipse Update Site</a>).
+ <p>
+ Get the code for the trunk or tag or branch (which ever one you want) from SVN:
+ <pre>mkdir /builduima
+cd /builduima
+svn export http://svn.apache.org/repos/asf/uima/uimaj/trunk uimasdk
+</pre>
+ This checks out the trunk into the directory /builduima/uimasdk. These
+ directory and folder names are arbitrary, and can be changed.
+ </p>
+ <p>Build the source and binary distributions by doing:
+ <pre style="font-size: 133%">cd uimasdk/uimaj
+mvn package -Papache-release</pre>
+ This Maven command will also sign the release.
</p>
- <p>Note: to get the PDFs built, you have to run this on a Windows machine.</p>
- <p>The build process for base UIMA builds individual Jar files suitable for uploading into a maven repository,
+ <p>The build process for base UIMA Java SDK 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 <code>target</code> directories of the individual projects they
- belong to. The assemblies (source and binary) are in the <code>uimaj-distr/target</code> directory.
+ belong to. The source assembly is in the <code>uimaj/target</code> directory and the binary assembly is
+ in the <code>uimaj-distr/target</code> directory.
</p>
</blockquote>
</p>
@@ -240,8 +237,23 @@
<tr><td>
<blockquote class="sectionBody">
<p>
- 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
+ The build process for UIMA-AS is similar:
+ <pre>mkdir /builduima
+cd /builduima
+svn export http://svn.apache.org/repos/asf/uima/uima-as/trunk uima-as
+</pre>
+ This checks out the trunk into the directory /builduima/uima-as.
+ </p>
+ <p>The uima-as build is done on top of an existing release of the UIMA Java SDK. The pom.xml file
+ in the uima-as-parent project has a property:
+ <code><uimajDependencyVersion>2.3.1</uimajDependencyVersion></code>, which is used
+ to specify the corresponding base uima level, which must exist in some Maven repository, or in the user's
+ local .m2 repository. During the build of the binary assembly for uima-as, the base uima Java SDK binary
+ assembly is unzipped and the uima-as components are added to it, and then the whole thing is re-packaged up.</p>
+ <p>Build the source and binary distributions by doing:
+ <pre>cd uima-as/uima-as
+mvn package -Papache-release</pre>
+ This Maven command will also sign the release.
</p>
</blockquote>
</p>
@@ -250,283 +262,25 @@
<div class="sectionTable">
<table class="sectionTable">
<tr><td>
- <a name="Building Apache UIMA Sandbox distributions"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building Apache UIMA Sandbox distributions</h1></a>
- </td></tr>
- <tr><td>
- <blockquote class="sectionBody">
- <p>
- 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 <code>SandboxDistr/annotator-package/build</code> you can create your own distribution.
- Start out in an empty directory and run: </p>
- <blockquote> <code>extractAndBuild.bat <tag name></code> </blockquote>
- <p>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.
- </p>
- </blockquote>
- </p>
- </td></tr>
- </table>
- <div class="sectionTable">
- <table class="sectionTable">
- <tr><td>
- <a name="Building the Eclipse Update Site"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building the Eclipse Update Site</h1></a>
- </td></tr>
- <tr><td>
- <blockquote class="sectionBody">
- <p>
- 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.
- </p>
- <p>
- 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:
- <ul>
- <li>uimaj-eclipse-feature-deployeditor (for the UIMA-AS editor for deployment descriptors)</li>
- <li>uimaj-eclipse-feature-runtime (for other plugins, and for building RCP applications)</li>
- <li>uimaj-eclipse-feature-tools (holds most of the UIMA Eclipse tooling</li>
- </ul>
- </p>
- <p>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.</p>
- <p>
- The Eclipse update site is built in 2 phases.
- <ol>
- <li>
- <p>The first phase occurs during the normal maven
- builds of the project - this phase builds the Jars that constitute the plugins.</p>
- </li>
- <li>
- <p>
- The second consists of several parts.
- </p>
- <p>The set of feature projects, uimaj-eclipse-feature-xxxxx, must all be updated for
- the current release. Generally, only the <code>pom.xml</code> and <code>feature.xml</code> files will
- need updating.</p>
- <p>Update the uimaj-eclipse-update-site project for the release: the files <code>pom.xml</code>
- and <code>site.xml</code>. Then execute the maven command
- <code>mvn install</code> on the uimaj-eclipse-update-site project.
- The POM for this is an aggregator POM and will recursively invoke <code>install</code> on the uimaj-eclipse-feature-xxxxx
- projects, to build their Jars.</p>
-
- <p>The result of running <code>mvn install</code> 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.</p>
- </li>
- </ol>
- </p>
- <p>
- 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".
- </p>
- <p>
- You can do this in one of 3 ways.
- </p>
- <p>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:
-</p>
- <pre>
-<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>
- </pre>
- <p>The second way to do this is to set an environment variable. Here's an example in Windows:</p>
- <longquote><code>set ECLIPSE_HOME=c:/your/path/to/eclipse</code></longquote>
- <p>The third way is to pass a command line argument to the maven command below, which looks like this:</p>
- <longquote><code>-Duima-maven-build-eclipse-home=c:/your/path/to/eclipse</code></longquote>
- </blockquote>
- </p>
- </td></tr>
- </table>
- <div class="sectionTable">
- <table class="sectionTable">
- <tr><td>
- <a name="Signing a distribution"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Signing a distribution</h1></a>
+ <a name="Building Apache UIMA Addons distributions"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Building Apache UIMA Addons distributions</h1></a>
</td></tr>
<tr><td>
<blockquote class="sectionBody">
<p>
- 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.
+ The build process for Addons is similar:
+ <pre>mkdir /builduima
+cd /builduima
+svn export http://svn.apache.org/repos/asf/uima/sandbox/trunk addons
+</pre>
+ This checks out the trunk into the directory /builduima/addons.
</p>
- <table class="subsectionTable">
- <tr><td>
-
-
-
- <a name="Getting started with release signing">
- <h2>Getting started with release signing
- </h2>
- </a>
- </td></tr>
- <tr><td>
- <blockquote class="subsectionBody">
- <p>
- 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 <a href="http://www.pgpi.org/doc/pgpintro/">
- good introduction to PGP</a> and digital certificates. We recommend reading this document front-to-back.
- There is also more general information on <a href="http://www.apache.org/dev/release-signing.html">
- signing Apache releases</a>. More information is also available <a href="http://wiki.apache.org/incubator/SigningReleases">
- on the wiki</a>. 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.
- </p>
- <p>
- Start by <a href="http://www.gnupg.org/download/">downloading GnuPG</a>. 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 <blockquote><code>gpg --gen-key</code></blockquote>
- This is pretty self-explanatory,
- some more information is <a href="http://www.apache.org/dev/release-signing.html#generate">in the
- release signing FAQ</a>. 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.
- </p>
- <p>
- You can now list your public key with the following command:
- <blockquote><code>gpg --armor --export</code></blockquote>
- The output will look like this:<blockquote>
- <code>
------BEGIN PGP PUBLIC KEY BLOCK-----<br />
-Version: GnuPG v1.4.6 (MingW32)<br />
-<br />
-mQGiBEWszKIRBACRscWnk1F408lWIZEgqx6OffiMtgApEVdl9UXXF2+DeS5WrHj0<br />
-1KDm9Q5Ir/o3f1qw7Il16Z496nDqmZHFKcrIgZvXcp5oCRE8sPMwdoy6X9kqVKug<br />
-...<br />
------END PGP PUBLIC KEY BLOCK-----
- </code>
- </blockquote>
- There are two places this output needs to go: the UIMA KEYS file, and a public key server.
- <ol>
- <li>
- Append your key (delimiting lines and all) to <code>uima-website/docs/KEYS</code>.
- 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.
- </li>
- <li>
- Upload your public key to <a href="http://pgp.mit.edu/">the MIT public key server</a> and any
- other key server you think is appropriate (follow instructions on website).
- </li>
- </ol>
- Your public key can later be used by our users to verify releases that you signed.
- </p>
- <p>
- You're now set up to do the actual release signing, and we'll tell you how in the next section.
- </p>
- </blockquote>
- </td></tr>
- </table>
- <table class="subsectionTable">
- <tr><td>
-
-
-
- <a name="Signing a Apache UIMA Release">
- <h2>Signing a Apache UIMA Release
- </h2>
- </a>
- </td></tr>
- <tr><td>
- <blockquote class="subsectionBody">
- <p>
- You can use the script <code>uimaj-distr/src/main/build/signRelease.sh</code> 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. </p>
- <p>To use the signRelease script, <code>cd</code> to <code>uimaj-distr</code> project, and
- issue the command:
- <blockquote><code>src/main/build/signRelease.sh <version> <passphrase></code></blockquote>
- For example: <code>src/main/build/signRelease.sh uimaj-2.3.0-incubating "Your passphrase in quotes"</code>
- Note that the passphrase needs quotes if it contains blanks or special characters.
- </p>
- <p>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.</p>
- </blockquote>
- </td></tr>
- </table>
- <table class="subsectionTable">
- <tr><td>
-
-
-
- <a name="Signing a Sandbox AnnotatorPackage Release">
- <h2>Signing a Sandbox AnnotatorPackage Release
- </h2>
- </a>
- </td></tr>
- <tr><td>
- <blockquote class="subsectionBody">
- <p>
- You can use the script <code>SandboxDistr/annotator-package/build/signRelease.sh</code> 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. </p>
- <p>To use the signRelease script, <code>cd</code> to <code>SandboxDistr/annotator-package</code> folder, and
- issue the command:
- <blockquote><code>build/signRelease.sh <version> <passphrase></code></blockquote>
- For example: <code>build/signRelease.sh uimaj-annotator-addons-2.2.2-incubating "passphrase in quotes"</code>
- <br />
- Note that the passphrase needs quotes if it contains blanks or special characters.
- </p>
- <p>This script will sign the binary and source release artifacts.</p>
- </blockquote>
- </td></tr>
- </table>
- <table class="subsectionTable">
- <tr><td>
-
-
-
- <a name="Signing an Eclipse update site">
- <h2>Signing an Eclipse update site
- </h2>
- </a>
- </td></tr>
- <tr><td>
- <blockquote class="subsectionBody">
- <p>This is one step in the Release process for the Eclipse update site, and is described on the
- <a href="release.html#Publish The Release">Doing a Release</a> page.</p>
- </blockquote>
- </td></tr>
- </table>
+ <p>Build the source and binary distributions by doing:
+ <pre>cd addons/addons
+mvn package -Papache-release</pre>
+ This Maven command will also sign the release.
+ </p>
+ <p>The uimaj-addons project contains in the target directory
+ the generated source-release.zip archive, and the binary archives.</p>
</blockquote>
</p>
</td></tr>
Modified: uima/site/trunk/uima-website/docs/release-before-2.3.1.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/release-before-2.3.1.html?rev=1063425&r1=1063424&r2=1063425&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/release-before-2.3.1.html (original)
+++ uima/site/trunk/uima-website/docs/release-before-2.3.1.html Tue Jan 25 19:47:47 2011
@@ -177,8 +177,8 @@
</td></tr>
<tr><td>
<blockquote class="sectionBody">
- <p class="note">These instructions are mostly for the 2.3.0 release. They are changing for the 2.3.1 release, and
- this page will be updated soon to reflect that.</p>
+ <p class="note">These instructions are for the 2.3.0 release. For the 2.3.1 and later release,
+please see <a href="release.html">this</a> page.</p>
<p>
<ul>
<li><a href="#Release Discussions - Release Plan">Release Discussions - Release Plan</a></li>
Modified: uima/site/trunk/uima-website/docs/release.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/release.html?rev=1063425&r1=1063424&r2=1063425&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/release.html (original)
+++ uima/site/trunk/uima-website/docs/release.html Tue Jan 25 19:47:47 2011
@@ -568,7 +568,8 @@ mvn install -Papache-release</pre>
first deleting any Jars that might be there from previous releases.</li>
-->
- <li>run the ant build script to pack the new plugin Jars, and generate the new site digest containing
+ <li>run <code>mvn package</code> on the uimaj-eclipse-update-site project
+ to pack the new plugin Jars, and generate the new site digest containing
the new features.</li>
<li>run the signEclipseUpdateSite.sh script to sign the new Jars and zip files the build script created.
Added: uima/site/trunk/uima-website/xdocs/distribution-before-2.3.1.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/distribution-before-2.3.1.xml?rev=1063425&view=auto
==============================================================================
--- uima/site/trunk/uima-website/xdocs/distribution-before-2.3.1.xml (added)
+++ uima/site/trunk/uima-website/xdocs/distribution-before-2.3.1.xml Tue Jan 25 19:47:47 2011
@@ -0,0 +1,350 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+<document>
+
+<properties>
+<title>Creating Distributions - version 2.3.0 and earlier</title>
+<author email="dev@uima.apache.org">Apache UIMA Documentation Team</author>
+</properties>
+
+<body>
+
+<section name="Building Apache UIMA distributions for release 2.3.0 and earlier">
+
+ <p style="font-size:125%">
+ This page describes how we build distributions for the 2.3.0 and earlier releases.
+ See <a href="distribution.html">this page</a> for information on
+ building distributions for the 2.3.1 and later releases.
+ </p>
+
+<h4>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.</h4>
+ <p>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).</p>
+
+ <p>
+ <ul>
+ <li><a href="#Building the Apache UIMA™ base distribution">Building the Apache UIMA base distribution</a></li>
+ <li><a href="#Building the Apache UIMA-AS distribution">Building the Apache UIMA-AS distribution</a></li>
+ <li><a href="#Building Apache UIMA Sandbox distributions">Building Apache UIMA Sandbox distributions</a></li>
+ <li><a href="#Building the Eclipse Update Site">Building the Eclipse Update Site</a></li>
+ <li><a href="#Signing a distribution">Signing a distribution</a>
+ <ul>
+ <li><a href="#Getting started with release signing">Getting started with release signing</a></li>
+ <li><a href="#Signing a Apache UIMA Release">Signing a Apache UIMA Release</a></li>
+ <li><a href="#Signing Sandbox AnnotatorPackage Release">Signing Sandbox AnnotatorPackage Release</a></li>
+ </ul>
+ </li>
+ </ul>
+</p>
+</section>
+
+<section name="Building the Apache UIMA base distribution">
+
+ <p class="note">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.</p>
+ <p>
+ Start by extracting and building the code manually as described on the
+ <a href="./svn.html">source code page</a>.
+ Once you have all that working, you can build a distribution with the help
+ of the scripts in <code>uimaj-distr/src/main/build</code>. Start out in an empty directory and
+ run: <blockquote> <code>extractAndBuild.bat</code>
+ from the uimaj-distr/src/main/build directory.</blockquote>
+ This will extract the source code from SVN, compile and run the tests, and finally build the
+ distribution artifacts. (It will not build the
+ <a href="#Building the Eclipse Update Site">Eclipse Update Site</a>).
+ </p>
+ <p>Note: to get the PDFs built, you have to run this on a Windows machine.</p>
+ <p>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 <code>target</code> directories of the individual projects they
+ belong to. The assemblies (source and binary) are in the <code>uimaj-distr/target</code> directory.
+ </p>
+</section>
+
+<section name="Building the Apache UIMA-AS distribution">
+ <p>
+ 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
+ </p>
+
+</section>
+<section name="Building Apache UIMA Sandbox distributions">
+
+
+ <p>
+ 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 <code>SandboxDistr/annotator-package/build</code> you can create your own distribution.
+ Start out in an empty directory and run: </p>
+ <blockquote> <code>extractAndBuild.bat <tag name></code> </blockquote>
+ <p>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.
+ </p>
+</section>
+
+<section name="Building the Eclipse Update Site">
+
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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:
+ <ul>
+ <li>uimaj-eclipse-feature-deployeditor (for the UIMA-AS editor for deployment descriptors)</li>
+ <li>uimaj-eclipse-feature-runtime (for other plugins, and for building RCP applications)</li>
+ <li>uimaj-eclipse-feature-tools (holds most of the UIMA Eclipse tooling</li>
+ </ul>
+ </p>
+ <p>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.</p>
+ <p>
+ The Eclipse update site is built in 2 phases.
+ <ol>
+ <li>
+ <p>The first phase occurs during the normal maven
+ builds of the project - this phase builds the Jars that constitute the plugins.</p>
+ </li>
+ <li>
+ <p>
+ The second consists of several parts.
+ </p>
+ <p>The set of feature projects, uimaj-eclipse-feature-xxxxx, must all be updated for
+ the current release. Generally, only the <code>pom.xml</code> and <code>feature.xml</code> files will
+ need updating.</p>
+ <p>Update the uimaj-eclipse-update-site project for the release: the files <code>pom.xml</code>
+ and <code>site.xml</code>. Then execute the maven command
+ <code>mvn install</code> on the uimaj-eclipse-update-site project.
+ The POM for this is an aggregator POM and will recursively invoke <code>install</code> on the uimaj-eclipse-feature-xxxxx
+ projects, to build their Jars.</p>
+
+ <p>The result of running <code>mvn install</code> 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.</p>
+ </li>
+ </ol>
+ </p>
+ <p>
+ 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".
+ </p>
+ <p>
+ You can do this in one of 3 ways.
+ </p>
+ <p>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:
+</p>
+<pre>
+<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>
+ </pre>
+
+ <p>The second way to do this is to set an environment variable. Here's an example in Windows:</p>
+ <longquote><code>set ECLIPSE_HOME=c:/your/path/to/eclipse</code></longquote>
+
+ <p>The third way is to pass a command line argument to the maven command below, which looks like this:</p>
+ <longquote><code>-Duima-maven-build-eclipse-home=c:/your/path/to/eclipse</code></longquote>.
+
+
+</section>
+
+<section name="Signing a distribution">
+
+ <p>
+ 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.
+ </p>
+
+ <subsection name="Getting started with release signing">
+
+ <p>
+ 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 <a href="http://www.pgpi.org/doc/pgpintro/">
+ good introduction to PGP</a> and digital certificates. We recommend reading this document front-to-back.
+ There is also more general information on <a href="http://www.apache.org/dev/release-signing.html">
+ signing Apache releases</a>. More information is also available <a href="http://wiki.apache.org/incubator/SigningReleases">
+ on the wiki</a>. 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.
+ </p>
+
+ <p>
+ Start by <a href="http://www.gnupg.org/download/">downloading GnuPG</a>. 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 <blockquote><code>gpg --gen-key</code></blockquote>
+ This is pretty self-explanatory,
+ some more information is <a href="http://www.apache.org/dev/release-signing.html#generate">in the
+ release signing FAQ</a>. 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.
+ </p>
+
+ <p>
+ You can now list your public key with the following command:
+ <blockquote><code>gpg --armor --export</code></blockquote>
+ The output will look like this:<blockquote>
+ <code>
+-----BEGIN PGP PUBLIC KEY BLOCK-----<br/>
+Version: GnuPG v1.4.6 (MingW32)<br/>
+<br/>
+mQGiBEWszKIRBACRscWnk1F408lWIZEgqx6OffiMtgApEVdl9UXXF2+DeS5WrHj0<br/>
+1KDm9Q5Ir/o3f1qw7Il16Z496nDqmZHFKcrIgZvXcp5oCRE8sPMwdoy6X9kqVKug<br/>
+...<br></br>
+-----END PGP PUBLIC KEY BLOCK-----
+ </code>
+ </blockquote>
+ There are two places this output needs to go: the UIMA KEYS file, and a public key server.
+ <ol>
+ <li>
+ Append your key (delimiting lines and all) to <code>uima-website/docs/KEYS</code>.
+ 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.
+ </li>
+ <li>
+ Upload your public key to <a href="http://pgp.mit.edu/">the MIT public key server</a> and any
+ other key server you think is appropriate (follow instructions on website).
+ </li>
+ </ol>
+ Your public key can later be used by our users to verify releases that you signed.
+ </p>
+
+ <p>
+ You're now set up to do the actual release signing, and we'll tell you how in the next section.
+ </p>
+
+ </subsection>
+
+ <subsection name="Signing a Apache UIMA Release">
+
+ <p>
+ You can use the script <code>uimaj-distr/src/main/build/signRelease.sh</code> 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. </p>
+
+ <p>To use the signRelease script, <code>cd</code> to <code>uimaj-distr</code> project, and
+ issue the command:
+ <blockquote><code>src/main/build/signRelease.sh <version> <passphrase></code></blockquote>
+ For example: <code>src/main/build/signRelease.sh uimaj-2.3.0-incubating "Your passphrase in quotes"</code>
+ Note that the passphrase needs quotes if it contains blanks or special characters.
+ </p>
+ <p>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.</p>
+ <!-- The command line for generating the signature file is
+ <blockquote><code>gpg - -passphrase "Your passphrase" - -output <artifact>.asc - -detach-sig - -armored <artifact></code></blockquote>
+ -->
+
+ <!--ol>
+ <li>
+ A PGP ASCII-armored detached signature file. 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. The command line for generating the signature file is
+ <blockquote><code>gpg - -passphrase "Your passphrase" - -output <artifact>.asc - -detach-sig - -armored <artifact></code></blockquote>
+ </li>
+ <li>
+ A MD5 message digest. This is a checksum a user can use to check the integrity of the
+ download. There are various tools to create MD5 checksums. Since we're using gpg anyway, here's
+ the gpg way: <blockquote><code>gpg - -print-md MD5 <artifact>.md5</code></blockquote>
+ </li>
+ <li>
+ A SHA1 message digest. This is a checksum a user can use to check the integrity of the
+ download. Here's how to create a SHA1 checksum with gpg: <blockquote><code>gpg - -print-md SHA1 <artifact>.sha1</code></blockquote>
+ </li>
+ </ol-->
+
+
+ <!--p>
+ To use the signing script mentioned above, <code>cd</code> to the directory with your release
+ artifacts and run: <blockquote> <code>signRelease.sh <release> <passphrase></code> </blockquote>
+ So for example: <blockquote> <code>signRelease.sh uimaj-2.1.0 "Your passphrase in quotes"</code> </blockquote>
+ </p-->
+ </subsection>
+ <subsection name="Signing a Sandbox AnnotatorPackage Release">
+
+ <p>
+ You can use the script <code>SandboxDistr/annotator-package/build/signRelease.sh</code> 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. </p>
+
+ <p>To use the signRelease script, <code>cd</code> to <code>SandboxDistr/annotator-package</code> folder, and
+ issue the command:
+ <blockquote><code>build/signRelease.sh <version> <passphrase></code></blockquote>
+ For example: <code>build/signRelease.sh uimaj-annotator-addons-2.2.2-incubating "passphrase in quotes"</code>
+ <br></br>
+ Note that the passphrase needs quotes if it contains blanks or special characters.
+ </p>
+ <p>This script will sign the binary and source release artifacts.</p>
+ </subsection>
+
+ <subsection name="Signing an Eclipse update site">
+ <p>This is one step in the Release process for the Eclipse update site, and is described on the
+ <a href="release.html#Publish The Release">Doing a Release</a> page.</p>
+ </subsection>
+</section>
+
+</body>
+</document>