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/08/05 22:31:52 UTC
svn commit: r1154374 - in /uima/site/trunk/uima-website:
docs/maven-design.html xdocs/maven-design.xml
Author: schor
Date: Fri Aug 5 20:31:51 2011
New Revision: 1154374
URL: http://svn.apache.org/viewvc?rev=1154374&view=rev
Log:
no Jira - update the docs on how we use maven, with respect to the addons build process details
Modified:
uima/site/trunk/uima-website/docs/maven-design.html
uima/site/trunk/uima-website/xdocs/maven-design.xml
Modified: uima/site/trunk/uima-website/docs/maven-design.html
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/docs/maven-design.html?rev=1154374&r1=1154373&r2=1154374&view=diff
==============================================================================
--- uima/site/trunk/uima-website/docs/maven-design.html (original)
+++ uima/site/trunk/uima-website/docs/maven-design.html Fri Aug 5 20:31:51 2011
@@ -186,6 +186,29 @@ building the various parts of UIMA.</p>
<a target="_blank" href="http://www.apache.org/dev/publishing-maven-artifacts.html">
http://www.apache.org/dev/publishing-maven-artifacts.html</a>.</p>
<p>This document covers how we use Maven for building Version: 2.3.1 and onwards.</p>
+ <ul>
+ <li><a href="#Nexus">Nexus use</a></li>
+ <li><a href="#POM Conventions">POM Conventions</a></li>
+ <li><a href="#Our POM hierarchy">POM Hierarchy</a></li>
+ <li><a href="#Selecting build alternatives based on the project">Selecting build alternatives based on the project</a></li>
+ <li><a href="#POM style">POM style</a></li>
+ <li><a href="#Release artifacts">Release artifacts</a></li>
+ <ul>
+ <li><a href="#LICENSE and NOTICE files">LICENSE and NOTICE files</a></li>
+ <li><a href="#Standard Artifacts" />Standard Artifacts</li>
+ </ul>
+ <li><a href="#Handling Documentation">Handling Documentation</a></li>
+ <li><a href="#Packaging Individual Projects">Packaging Individual Projects</a>
+ <ul>
+ <li><a href="#Common conventions individual projects">Common conventions for structuring individually releaseable project</a></li>
+ <li><a href="#Conventions for PEARs">Conventions for structuring individual projects released as PEARs</a></li>
+ </ul>
+ </li>
+ <li><a href="#Building Assemblies for Distribution">Building Assemblies for Distribution</a></li>
+ <li><a href="#Special resources for build">Special resources for build</a></li>
+ <li><a href="#Using the Release Audit Tool (RAT)">Using the Release Audit Tool (RAT)</a></li>
+ <li><a href="#Lifecycle for building addons">Lifecycle for building addons</a></li>
+ </ul>
<table class="subsectionTable">
<tr><td>
@@ -252,7 +275,7 @@ for purposes of building multi-module th
For clarity,
we mostly keep these two uses in separate POMs: parent POMs do not do aggregation,
and aggregation POMs do not do common factoring.</p>
- <p>The UIMA Project as one common parent pom, called "parent-pom", that contains common
+ <p>The UIMA Project has one common parent pom, called "parent-pom", that contains common
things for all the sub-projects. Each multi-module sub-project, for instance, the UIMA Java SDK (uimaj),
contains, in turn, a sub-project common parent pom for all the modules in that project.</p>
<p>The Project-wide parent pom and related build artifacts are kept in a separate part of
@@ -287,11 +310,12 @@ our svn tree, in a top level directory n
existence of the directory <code>src/docbook</code> in the project.</p>
<p>These are the current marker-file kinds:
<ul>
- <li>marker-file-identifying-standard-pear</li>
- <li>marker-file-identifying-single-project</li>
<li>marker-file-identifying-parent-pom</li>
<li>marker-file-identifying-eclipse-plugin</li>
<li>marker-file-identifying-eclipse-feature</li>
+ <li>marker-file-identifying-single-project</li>
+ <li>marker-file-identifying-standard-pear</li>
+ <li>marker-file-identifying-osgi-project</li>
</ul>
</p>
</blockquote>
@@ -318,7 +342,7 @@ our svn tree, in a top level directory n
<p>So, If this does not correspond to how the website is set up,
please specify the url that is correct for the new project.</p>
</li>
- <li>The SCM connection is needed for releasing - and needs to be accurate for this
+ <li>The SCM connection is needed for doing releases - and needs to be accurate for this
component. The same defaulting is applied as above, which is incorrect for our
flat layout, so each POM needs to have an explicit SCM element.</li>
<li>The POM's "version" is stated literally, not via a "property", etc.
@@ -328,7 +352,9 @@ our svn tree, in a top level directory n
<li>The POM's groupId is omitted if it's the same as the parent pom's
(which is true for all of our projects except our top-most parent pom);
if omitted, it inherits from the parent.</li>
- <li>The packaging is omitted if it is "jar".</li>
+ <li>The packaging is omitted if it is "jar".</li>
+ <li>In the <code>build</code> section, the <code><groupId></code> for
+ standard maven plugins is omitted.</li>
</ul>
</p>
</blockquote>
@@ -344,21 +370,26 @@ our svn tree, in a top level directory n
<blockquote class="sectionBody">
<p>We follow the standard release process for Maven-based artifacts at Apache,
documented <a target="_blank" href="http://www.apache.org/dev/publishing-maven-artifacts.html">here.</a></p>
- <p>For each artifact, the release process builds additional artifacts, and
- attaches them to the main one, so they will "go along with" the main artifact during
- Maven deployment to repositories.</p>
+ <p>For each artifact, the release process may build additional artifacts, and
+ attach them to the main one, so they will "go along with" the main artifact during
+ Maven deployment to repositories. Some of these are:</p>
<ul>
<li>
sources.jar - holds the source files - this is for IDEs that want to refer to the source
</li>
- <li>
- source-release.zip - only for the top-most project in an aggregate build -
- this is the same as the sources, but includes all other files
+ <li><p>
+ source-release.zip. This is the same as the sources, but includes all other files
(such as the pom.xml) not under the /src
directory, needed for building.
The intent is that this is the same as the SVN checked-in files, and once unzipped, this
should be "buildable" by doing "mvn install", etc. in the unzipped directory.
+ </p>
+ <p><code>source-release.zip</code> files for multi-project aggregates (such as the main
+ UIMA SDK) are not "attached", and are not uploaded to maven for distribution; instead,
+ these are considered the main binary artifacts for the project and are distributed
+ using Apache's own mirroring distribution system.
+ </p>
</li>
</ul>
<p>
@@ -375,6 +406,75 @@ our svn tree, in a top level directory n
+ <a name="LICENSE and NOTICE files">
+ <h2>LICENSE and NOTICE files
+ </h2>
+ </a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="subsectionBody">
+ <p>
+ Things that are distributed from Apache need LICENSE and NOTICE files. We have several kinds
+ of distributions:
+ <ul>
+ <li>Releases
+ <ul>
+ <li>source-release.zip files</li>
+ <li>binary (built) packagings
+ <ul>
+ <li>Binary assemblies
+ <ul>
+ <li>Multi-project assemblies, like our main UIMA SDK</li>
+ <li>Single-project assemblies, like our individual add-on projects</li>
+ </ul>
+ </li>
+ <li>uploaded to main Maven Repository as part of releasing:
+ <ul>
+ <li>Individual Jars</li>
+ <li>PEAR packages of some individual projects</li>
+ <li>OSGi packaging of some individual projects</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>SVN
+ </li>
+ </ul>
+ </p>
+ <h3>Two kinds of LICENSE/NOTICE files</h3>
+ <p>There are typically two versions of these files, corresponding to source (only)
+ distributions versus other distributions which include "dependent" artifacts, which
+ may have their own separate license and notice information. The source (only)
+ versions of these files are in SVN at the top level of various project hierarchies.
+ </p>
+ <p class="Note">For some packagings of source artifacts, such as JARs for
+ projects that are part of bigger assemblies, the projects do not contain individual
+ license and notice files (see for instance, <code>.../uimaj/trunk/uimaj-core</code>.
+ For these, a standard LICENSE and NOTICE is computed using a template, augmented
+ if needed by additions from the project's <code>pom</code>.</p>
+ <p>The SVN itself has a top level license / notice file,
+ for all nodes under the top areas (uima/xxx/trunk, tags, etc.).
+ All major releasable things (other than projects for Jars which are always released
+ as part of an assembly - such as the Jars which make up the UIMA SDK), have top
+ level license and notice files in their top most project; these are for the
+ source, only, and do not cover the dependencies (if any) that might be included with
+ a binary-style release.
+ </p>
+ <p>Many of our packagings include dependencies, including OSGi and PEAR packagings,
+ as well as normal <code>binary</code> assemblies.
+ The license and notice for these packagings is made by merging the license and notice
+ files from the source artifact plus those from all the dependent artifacts
+ (removing duplications).</p>
+ </blockquote>
+ </td></tr>
+ </table>
+ <table class="subsectionTable">
+ <tr><td>
+
+
+
<a name="Standard Artifacts">
<h2>Standard Artifacts
</h2>
@@ -383,9 +483,8 @@ our svn tree, in a top level directory n
<tr><td>
<blockquote class="subsectionBody">
<p>The release process includes standard boiler-plate things in standard places.
- The Maven remote-resources-plugin
- is used to get these resources from a special a UIMA build artifact (uima-build-resources),
- customizing them for the particular project:
+ The Maven remote-resources-plugin is used to get these resources from a special
+ UIMA build artifact (uima-build-resources), and customizes them for the particular project:
<ul><li>The DEPENDENCIES file is generated from the
transitive closure of the dependencies in the POM.</li>
<li>The NOTICES file is sometimes augmented with additional text
@@ -393,7 +492,7 @@ our svn tree, in a top level directory n
in the files, per the Apache practice for moving these to the NOTICE file).
</li></ul>
</p>
- <p>These resources after customization are placed in the project's
+ <p>These resources, after customization, are placed in the project's
target/maven-shared-archive-resources/META-INF/
directory. Later steps in the build use this directory for two purposes:
<ul><li>adding this information to any JAR that might be built</li>
@@ -403,21 +502,28 @@ our svn tree, in a top level directory n
</p>
<p><b><u>Overriding on a per-project basis:</u></b>
Files that the remote-resources-plugin obtains and places
- in the target/maven-shared-archive-resources/META-INF/ directory can be overridden
- by including identically named files at the top level of the project.
- This is commonly used for add-on projects having a different LICENSE or NOTICE file.</p>
- <p>Note that there are sometimes two sets of LICENSE / NOTICE files - one for the source distribution,
+ in the target/maven-shared-archive-resources/META-INF/ directory are be overridden
+ by identically named files at the top level of the project.
+ </p>
+ <p>Note that there are two sets of LICENSE / NOTICE files for distributable entities -
+ one for the source distribution,
and one for the binary distribution. This is because the source distribution rarely needs other
- than the standard LICENSE/NOTICE files, for example, because it is
- (usually) only distributing source; while the
+ than the standard LICENSE/NOTICE files because it is
+ (usually) only distributing Apache-authored source; while the
binary distribution often distributes additional components that are licensed under other
- licenses, with additional NOTICE requirements - in which case, the LICENSE and NOTICE files
+ licenses, with perhaps additional NOTICE requirements - in which case, the LICENSE and NOTICE files
contains all of the required licenses and notices for everything
being distributed.</p>
<p style="margin-left: 3em">
- For <i>binary</i> distributions, the LICENSE and NOTICE files
+ For <code>binary</code> distributions, the LICENSE and NOTICE files
are taken from src/main/readme/ directory.
</p>
+ <p class="note">
+ Some addon projects have just a single st of LICENSE and NOTICE at the top level.
+ In this case, these are used for both the source and binary distribution, and they
+ therefore need to cover everything distributed with the binary distribution (even
+ if these are not delivered with the source distribution).
+ </p>
<br />
<br />
<p>This next table summarizes the packaging artifacts and how and where they are
@@ -433,76 +539,62 @@ our svn tree, in a top level directory n
</tr>
<tr>
- <td><p>LICENSE, NOTICE, DEPENDENCIES.</p>
- <!--p>Note that DEPENDENCIES are not (currently) in
- our "binary" assembly distributions.</p--></td>
+ <td><p>LICENSE, NOTICE, DEPENDENCIES.</p></td>
<!-- variants -->
<td><p>Standard, for source distribution</p>
<p>Alternate: has extra Notice element used for copyrights moved to Notice file.</p>
<p>Alternate2: for binary assemblies, the LICENSE and NOTICE
are customized for each binary assembly.</p>
</td>
- <td><p>uima-build-resources (in the build tooling).</p>
+ <!-- origin -->
+ <td><p>For source distributions: uima-build-resources (in the build tooling).</p>
<p>Additional text for NOTICE (if needed) comes from
the property <code><postNoticeText></code>in the build POM.
For many cases, the additional copyright notice is for
IBM contributed code, which can be included using
<code><postNoticeText>${ibmNoticeText}</postNoticeText></code>.</p>
- <p>For binary assemblies, comes from either
- <ul><li>src/main/readme/, or</li>
- <li>top level (for Addons)</li>
- </ul>
+ <p>For binary distributions, comes from src/main/readme/
</p>
</td>
<!-- Targets -->
- <td><p>Jars: goes into the MANIFEST.MF.
- <p>Source-Release Assemblies:</p>
- goes into the zip as top level files.</p>
- <p>Custom Binary assemblies: goes into the zip / tar as top level files.</p>
+ <td><p>Jars: goes into META-INF.
+ <p>Source-Release zips, source assemblies, binary assemblies, PEAR files, OSGi artifacts:</p>
+ goes into the zip/tar as top level files.</p>
</td>
<!-- Method -->
<td><p>org.apache.uima:parent-pom configures the remote-resources plugin
- to copy these into
+ to copy the standard LICENSE/NOTICE/DEPENDENCIES into
target/maven-shared-archive-resources/META-INF/
- directory. This info is then included in any Jars that are built.</p>
+ directory. This info is then included in any Jars that are built, in META-INF.</p>
<p>During release (only) (apache-release profile activated)
the information in target/maven-shared-archive-resources/META-INF/
is copied to the top level of the source-release archive.
Any versions of these files at the project's top level
will subsequently override these, at the top level of the archive.</p>
- <p style="margin-left=3em">The common parent-pom configures the property
+ <!--p style="margin-left=3em">The common parent-pom configures the property
<code>sourceReleaseAssemblyDescriptor</code> to "multimodule-source-release",
this property value is used by the common Apache POM to pick the
source assembly descriptor from the
- uima-build-resources.</p>
- <p>For binary distributions, done with -distr projects,
- these files come from src/main/readme/. For binary distributions,
- done using single-project parent (add-ons, typically), these files
- are copied from the top level of the project into the archive.</p></td>
+ uima-build-resources.</p-->
+ <p>For PEAR, OSGi, and binary assemblies,
+ these files come from src/main/readme/, the <code>maven-resources-plugin</code>
+ uses the <code>copy-resources</code> goal to copy these.</p></td>
</tr>
<tr>
<td>README.txt</td>
<!-- variants -->
<td />
- <td><p>For -distr poms, for source distributions, these come from
- same-named files at the top level of the -distr project.
- For binary distributions, the custom assembly specifies where these
- files come from (typically src/main/readme).
- </p>
- <p>For Addon projects, if there is a README at the top level, this
- is copied into both the source and binary distributions, at the top level of the archive.</p>
- </td>
- <td>source-release.zips and binary distribution releases (not in Jars).
- Goes at the top level of archive.
+ <td><p>For PEAR, OSGi, binary assemblies, and source zips distributions, these come from
+ same-named files at the top level of the project doing the creating of the release artifact.
+ </p>
</td>
+ <td>Included in all packagings, except project Jars at the top level of package.</td>
<td>
<p>For source release building, during release (only) (apache-release profile activated)
parent-pom-top configures the assembly plugin for source assemblies to use
the multimodule-source-release in uima-build-resources. This copies
the README file from the top level into the top level of the archive.
</p>
- <p>For binary distributions, the assembly copies the README from src/main/readme/
- or from the top level in the project.</p>
</td>
</tr>
@@ -514,17 +606,14 @@ our svn tree, in a top level directory n
<!-- variants -->
<td />
<!-- Sources -->
- <td><p>For -distr poms, source for these was in src/main/readme/, but is now
- at the top level (to reduce configuration by following more conventions)</p>
- <p>For (some) Addons, there is a RELEASE_NOTES at the top level, which
- is copied into the source and binary distributions to the top level of the archive.</p>
+ <td><p>At the top level</p>
</td>
<!-- Targets -->
- <td>source-release.zips for some projects and binary distribution releases (not in Jars).
- Goes at the top level of archive.</td>
+ <td>Included in all packagings, except project Jars at the top level of package.</td>
<!-- Method -->
<td>
- <p>During release builds the assembly is configured to copy these from the top
+ <p>During release builds the assembly or maven-resources-plugin
+ is configured to copy these from the top
level of the project to the top level of the archive.
</p>
</td>
@@ -545,7 +634,7 @@ our svn tree, in a top level directory n
<td>This is a computed resource.</td>
<!-- Targets -->
<td>This is generated into the top level of the project, and then goes
- into any archives that are produced, at the top level.</td>
+ into all packagings except OSGi, at the top level.</td>
<!-- Method -->
<td>
<p>The build process runs the maven changes:jira-report plugin to generate this.
@@ -650,8 +739,8 @@ our svn tree, in a top level directory n
</p>
<p>If an annotator isn't suitable for PEAR packaging, perhaps because it is inappropriate to have
one pre-done main descriptor, then the annotator can be packaged as a single-project, instead, by
- making the POM's parent parent-pom-single-project.</p>
- <h2>Common conventions for structuring individually releaseable projects</h2>
+ marking the POM's parent parent-pom-single-project.</p>
+ <h2 id="Common conventions individual projects">Common conventions for structuring individually releaseable projects</h2>
<p>Use these conventions to get your annotator properly packaged when you use the parent-pom-annotator or
the parent-pom-single-project as your parent pom:
<ul>
@@ -674,7 +763,7 @@ our svn tree, in a top level directory n
</li>
</ul>
</p>
- <h2>Conventions for structuring individual projects released as PEARs</h2>
+ <h2 id="Conventions for PEARs">Conventions for structuring individual projects released as PEARs</h2>
<p>
<ul>
<li>Using the following folders at the top level of your project (which
@@ -720,8 +809,8 @@ our svn tree, in a top level directory n
<ul>
<li>UIMA - the base Java framework</li>
<li>UIMA-AS - the asynchronous scaleout add-on</li>
- <li>UIMA Add-ons - not decided yet, but it's likely we'll just release these as individual projects.
- So there is no add-ons-distr project (yet).</li>
+ <li>UIMA Add-ons - These are released as a collection. Future updates will
+ likely release these individually.</li>
<!--li>UIMA Add-ons - annotators and other add-on components such as the SimpleServer</li-->
<li>UIMACPP - the C++ framework</li>
</ul>
@@ -733,17 +822,23 @@ our svn tree, in a top level directory n
<div class="sectionTable">
<table class="sectionTable">
<tr><td>
- <a name="Build resources"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Build resources</h1></a>
+ <a name="Special resources for build"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Special resources for build</h1></a>
</td></tr>
<tr><td>
<blockquote class="sectionBody">
<p>During the build process, several resources are used, and are built into Maven Artifact Jars with
- Maven coordinates:
+ Maven coordinates. These projects are in the <code>build</code> section of SVN.
<ul>
- <li>uima-jar-resource-bundle - this is the standard License Notice and Dependencies from the
+ <li>uima-build-resources - this contains various resources used in the build process
+ <ul>
+ <li>the standard License Notice and Dependencies from the
Apache common parent pom, except it allows adding post-Notice text. We use this when
- we need to include the IBM Copyright notice, moved here from donated code from IBM.
- This also has an override for the multi-module source release assembly.</li>
+ we need to include the IBM Copyright notice, moved here from donated code from IBM.</li>
+ <li>an override for the multi-module source release assembly</li>
+ <li>the binary assembly descriptor for single-projects.</li>
+ <li>common specification for the titlepage of docbooks</li>
+ </ul>
+ </li>
<li>uima-docbook-olink - this is the shared
<a target="_blank" href="dev-docbook.html#Cross Referencing among UIMA Docbooks">olink</a> data.
This project's source contains the
@@ -752,9 +847,7 @@ our svn tree, in a top level directory n
This artifact is not released, it always stays at 1-SNAPSHOT level, but can be deployed
to the snapshot repository for sharing with others.
</li>
- <li>uima-docbook-resource-bundle - holds common information needed by docbook builds, including
- the specification for the titlepage.</li>
- <li>uima-assembly-single-project - holds the binary assembly descriptor for single-projects.</li>
+
</ul></p>
<p>There is also one custom Maven plugin (uima-build-helper-maven-plugin)
which is used to get the build month and build year into properties.
@@ -781,6 +874,39 @@ our svn tree, in a top level directory n
</p>
</td></tr>
</table>
+ <div class="sectionTable">
+ <table class="sectionTable">
+ <tr><td>
+ <a name="Lifecycle for building addons"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/> Lifecycle for building addons</h1></a>
+ </td></tr>
+ <tr><td>
+ <blockquote class="sectionBody">
+ <p>Addon projects have multiple binary build artifacts:
+ <ul>
+ <li>binary assembly for the individual addon</li>
+ <li>binary assembly for aggregate of all the addons</li>
+ <li>PEAR packaging</li>
+ <li>OSGi packaging</li>
+ </ul>
+ </p>
+ <p>Since these have many common parts, we use the maven lifecycle to order building of shared
+ common things ahead of their use:
+ <ul>
+ <li>package phase: build JARs, docbooks, etc.</li>
+ <li>pre-integration-test phase: this is the first phase after <code>package</code>, and is
+ used to copy the Jar and docbook processing results to a common directory structure (base-bin).</li>
+ <li>integration-test phase: this is the 2nd phas after <code>package</code>, and is
+ used to copy the common things from base-bin to places for building the PEAR and OSGi artifacts.
+ It is also used for running the packaging steps sequentially, after the copy, for the PEAR, OSGi,
+ and single project assemblies.</li>
+ <li>post-integration-test phase: this is used to mark the generated PEAR file for "attachment"
+ using the maven-build-helper, so it gets deployed to the maven repositories.</li>
+ </ul>
+ </p>
+ </blockquote>
+ </p>
+ </td></tr>
+ </table>
</td>
</tr>
<!-- FOOTER -->
Modified: uima/site/trunk/uima-website/xdocs/maven-design.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/maven-design.xml?rev=1154374&r1=1154373&r2=1154374&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/maven-design.xml (original)
+++ uima/site/trunk/uima-website/xdocs/maven-design.xml Fri Aug 5 20:31:51 2011
@@ -28,6 +28,7 @@ under the License.
<body>
<section name="Maven use for Apache UIMA builds">
+
<p>This is developer information, mostly. It documents how we are using Maven for
building the various parts of UIMA.</p>
@@ -39,6 +40,30 @@ building the various parts of UIMA.</p>
http://www.apache.org/dev/publishing-maven-artifacts.html</a>.</p>
<p>This document covers how we use Maven for building Version: 2.3.1 and onwards.</p>
+
+ <ul>
+ <li><a href="#Nexus">Nexus use</a></li>
+ <li><a href="#POM Conventions">POM Conventions</a></li>
+ <li><a href="#Our POM hierarchy">POM Hierarchy</a></li>
+ <li><a href="#Selecting build alternatives based on the project">Selecting build alternatives based on the project</a></li>
+ <li><a href="#POM style">POM style</a></li>
+ <li><a href="#Release artifacts">Release artifacts</a></li>
+ <ul>
+ <li><a href="#LICENSE and NOTICE files">LICENSE and NOTICE files</a></li>
+ <li><a href="#Standard Artifacts"></a>Standard Artifacts</li>
+ </ul>
+ <li><a href="#Handling Documentation">Handling Documentation</a></li>
+ <li><a href="#Packaging Individual Projects">Packaging Individual Projects</a>
+ <ul>
+ <li><a href="#Common conventions individual projects">Common conventions for structuring individually releaseable project</a></li>
+ <li><a href="#Conventions for PEARs">Conventions for structuring individual projects released as PEARs</a></li>
+ </ul>
+ </li>
+ <li><a href="#Building Assemblies for Distribution">Building Assemblies for Distribution</a></li>
+ <li><a href="#Special resources for build">Special resources for build</a></li>
+ <li><a href="#Using the Release Audit Tool (RAT)">Using the Release Audit Tool (RAT)</a></li>
+ <li><a href="#Lifecycle for building addons">Lifecycle for building addons</a></li>
+ </ul>
<subsection name="Nexus">
@@ -82,7 +107,7 @@ for purposes of building multi-module th
we mostly keep these two uses in separate POMs: parent POMs do not do aggregation,
and aggregation POMs do not do common factoring.</p>
-<p>The UIMA Project as one common parent pom, called "parent-pom", that contains common
+<p>The UIMA Project has one common parent pom, called "parent-pom", that contains common
things for all the sub-projects. Each multi-module sub-project, for instance, the UIMA Java SDK (uimaj),
contains, in turn, a sub-project common parent pom for all the modules in that project.</p>
@@ -113,11 +138,12 @@ our svn tree, in a top level directory n
<p>These are the current marker-file kinds:
<ul>
- <li>marker-file-identifying-standard-pear</li>
- <li>marker-file-identifying-single-project</li>
<li>marker-file-identifying-parent-pom</li>
<li>marker-file-identifying-eclipse-plugin</li>
<li>marker-file-identifying-eclipse-feature</li>
+ <li>marker-file-identifying-single-project</li>
+ <li>marker-file-identifying-standard-pear</li>
+ <li>marker-file-identifying-osgi-project</li>
</ul>
</p>
@@ -137,7 +163,7 @@ our svn tree, in a top level directory n
<p>So, If this does not correspond to how the website is set up,
please specify the url that is correct for the new project.</p>
</li>
- <li>The SCM connection is needed for releasing - and needs to be accurate for this
+ <li>The SCM connection is needed for doing releases - and needs to be accurate for this
component. The same defaulting is applied as above, which is incorrect for our
flat layout, so each POM needs to have an explicit SCM element.</li>
<li>The POM's "version" is stated literally, not via a "property", etc.
@@ -147,7 +173,9 @@ our svn tree, in a top level directory n
<li>The POM's groupId is omitted if it's the same as the parent pom's
(which is true for all of our projects except our top-most parent pom);
if omitted, it inherits from the parent.</li>
- <li>The packaging is omitted if it is "jar".</li>
+ <li>The packaging is omitted if it is "jar".</li>
+ <li>In the <code>build</code> section, the <code><groupId></code> for
+ standard maven plugins is omitted.</li>
</ul>
</p>
@@ -157,21 +185,26 @@ our svn tree, in a top level directory n
<p>We follow the standard release process for Maven-based artifacts at Apache,
documented <a target="_blank"
href="http://www.apache.org/dev/publishing-maven-artifacts.html">here.</a></p>
- <p>For each artifact, the release process builds additional artifacts, and
- attaches them to the main one, so they will "go along with" the main artifact during
- Maven deployment to repositories.</p>
+ <p>For each artifact, the release process may build additional artifacts, and
+ attach them to the main one, so they will "go along with" the main artifact during
+ Maven deployment to repositories. Some of these are:</p>
<ul>
<li>
sources.jar - holds the source files - this is for IDEs that want to refer to the source
</li>
- <li>
- source-release.zip - only for the top-most project in an aggregate build -
- this is the same as the sources, but includes all other files
+ <li><p>
+ source-release.zip. This is the same as the sources, but includes all other files
(such as the pom.xml) not under the /src
directory, needed for building.
The intent is that this is the same as the SVN checked-in files, and once unzipped, this
should be "buildable" by doing "mvn install", etc. in the unzipped directory.
+ </p>
+ <p><code>source-release.zip</code> files for multi-project aggregates (such as the main
+ UIMA SDK) are not "attached", and are not uploaded to maven for distribution; instead,
+ these are considered the main binary artifacts for the project and are distributed
+ using Apache's own mirroring distribution system.
+ </p>
</li>
</ul>
<p>
@@ -184,12 +217,72 @@ our svn tree, in a top level directory n
<code>-Papache-release</code> to the non-release Maven build commands.
</p>
+ <subsection name="LICENSE and NOTICE files">
+ <p>
+ Things that are distributed from Apache need LICENSE and NOTICE files. We have several kinds
+ of distributions:
+ <ul>
+ <li>Releases
+ <ul>
+ <li>source-release.zip files</li>
+ <li>binary (built) packagings
+ <ul>
+ <li>Binary assemblies
+ <ul>
+ <li>Multi-project assemblies, like our main UIMA SDK</li>
+ <li>Single-project assemblies, like our individual add-on projects</li>
+ </ul>
+ </li>
+ <li>uploaded to main Maven Repository as part of releasing:
+ <ul>
+ <li>Individual Jars</li>
+ <li>PEAR packages of some individual projects</li>
+ <li>OSGi packaging of some individual projects</li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ <li>SVN
+ </li>
+ </ul>
+ </p>
+
+ <h3>Two kinds of LICENSE/NOTICE files</h3>
+
+ <p>There are typically two versions of these files, corresponding to source (only)
+ distributions versus other distributions which include "dependent" artifacts, which
+ may have their own separate license and notice information. The source (only)
+ versions of these files are in SVN at the top level of various project hierarchies.
+ </p>
+ <p class="Note">For some packagings of source artifacts, such as JARs for
+ projects that are part of bigger assemblies, the projects do not contain individual
+ license and notice files (see for instance, <code>.../uimaj/trunk/uimaj-core</code>.
+ For these, a standard LICENSE and NOTICE is computed using a template, augmented
+ if needed by additions from the project's <code>pom</code>.</p>
+
+ <p>The SVN itself has a top level license / notice file,
+ for all nodes under the top areas (uima/xxx/trunk, tags, etc.).
+ All major releasable things (other than projects for Jars which are always released
+ as part of an assembly - such as the Jars which make up the UIMA SDK), have top
+ level license and notice files in their top most project; these are for the
+ source, only, and do not cover the dependencies (if any) that might be included with
+ a binary-style release.
+ </p>
+
+ <p>Many of our packagings include dependencies, including OSGi and PEAR packagings,
+ as well as normal <code>binary</code> assemblies.
+ The license and notice for these packagings is made by merging the license and notice
+ files from the source artifact plus those from all the dependent artifacts
+ (removing duplications).</p>
+ </subsection>
+
<subsection name="Standard Artifacts">
<p>The release process includes standard boiler-plate things in standard places.
- The Maven remote-resources-plugin
- is used to get these resources from a special a UIMA build artifact (uima-build-resources),
- customizing them for the particular project:
+ The Maven remote-resources-plugin is used to get these resources from a special
+ UIMA build artifact (uima-build-resources), and customizes them for the particular project:
<ul><li>The DEPENDENCIES file is generated from the
transitive closure of the dependencies in the POM.</li>
<li>The NOTICES file is sometimes augmented with additional text
@@ -198,7 +291,7 @@ our svn tree, in a top level directory n
</li></ul>
</p>
- <p>These resources after customization are placed in the project's
+ <p>These resources, after customization, are placed in the project's
target/maven-shared-archive-resources/META-INF/
directory. Later steps in the build use this directory for two purposes:
<ul><li>adding this information to any JAR that might be built</li>
@@ -209,23 +302,31 @@ our svn tree, in a top level directory n
<p><b><u>Overriding on a per-project basis:</u></b>
Files that the remote-resources-plugin obtains and places
- in the target/maven-shared-archive-resources/META-INF/ directory can be overridden
- by including identically named files at the top level of the project.
- This is commonly used for add-on projects having a different LICENSE or NOTICE file.</p>
+ in the target/maven-shared-archive-resources/META-INF/ directory are be overridden
+ by identically named files at the top level of the project.
+ </p>
- <p>Note that there are sometimes two sets of LICENSE / NOTICE files - one for the source distribution,
+ <p>Note that there are two sets of LICENSE / NOTICE files for distributable entities -
+ one for the source distribution,
and one for the binary distribution. This is because the source distribution rarely needs other
- than the standard LICENSE/NOTICE files, for example, because it is
- (usually) only distributing source; while the
+ than the standard LICENSE/NOTICE files because it is
+ (usually) only distributing Apache-authored source; while the
binary distribution often distributes additional components that are licensed under other
- licenses, with additional NOTICE requirements - in which case, the LICENSE and NOTICE files
+ licenses, with perhaps additional NOTICE requirements - in which case, the LICENSE and NOTICE files
contains all of the required licenses and notices for everything
being distributed.</p>
<p style="margin-left: 3em">
- For <i>binary</i> distributions, the LICENSE and NOTICE files
+ For <code>binary</code> distributions, the LICENSE and NOTICE files
are taken from src/main/readme/ directory.
</p>
+
+ <p class="note">
+ Some addon projects have just a single st of LICENSE and NOTICE at the top level.
+ In this case, these are used for both the source and binary distribution, and they
+ therefore need to cover everything distributed with the binary distribution (even
+ if these are not delivered with the source distribution).
+ </p>
<br/><br/>
<p>This next table summarizes the packaging artifacts and how and where they are
located and added during the build process.</p>
@@ -241,76 +342,62 @@ our svn tree, in a top level directory n
</tr>
<tr>
- <td><p>LICENSE, NOTICE, DEPENDENCIES.</p>
- <!--p>Note that DEPENDENCIES are not (currently) in
- our "binary" assembly distributions.</p--></td>
+ <td><p>LICENSE, NOTICE, DEPENDENCIES.</p></td>
<!-- variants -->
<td><p>Standard, for source distribution</p>
<p>Alternate: has extra Notice element used for copyrights moved to Notice file.</p>
<p>Alternate2: for binary assemblies, the LICENSE and NOTICE
are customized for each binary assembly.</p>
</td>
- <td><p>uima-build-resources (in the build tooling).</p>
+ <!-- origin -->
+ <td><p>For source distributions: uima-build-resources (in the build tooling).</p>
<p>Additional text for NOTICE (if needed) comes from
the property <code><postNoticeText></code>in the build POM.
For many cases, the additional copyright notice is for
IBM contributed code, which can be included using
<code><postNoticeText>${ibmNoticeText}</postNoticeText></code>.</p>
- <p>For binary assemblies, comes from either
- <ul><li>src/main/readme/, or</li>
- <li>top level (for Addons)</li>
- </ul>
+ <p>For binary distributions, comes from src/main/readme/
</p>
</td>
<!-- Targets -->
- <td><p>Jars: goes into the MANIFEST.MF.
- <p>Source-Release Assemblies:</p>
- goes into the zip as top level files.</p>
- <p>Custom Binary assemblies: goes into the zip / tar as top level files.</p>
+ <td><p>Jars: goes into META-INF.
+ <p>Source-Release zips, source assemblies, binary assemblies, PEAR files, OSGi artifacts:</p>
+ goes into the zip/tar as top level files.</p>
</td>
<!-- Method -->
<td><p>org.apache.uima:parent-pom configures the remote-resources plugin
- to copy these into
+ to copy the standard LICENSE/NOTICE/DEPENDENCIES into
target/maven-shared-archive-resources/META-INF/
- directory. This info is then included in any Jars that are built.</p>
+ directory. This info is then included in any Jars that are built, in META-INF.</p>
<p>During release (only) (apache-release profile activated)
the information in target/maven-shared-archive-resources/META-INF/
is copied to the top level of the source-release archive.
Any versions of these files at the project's top level
will subsequently override these, at the top level of the archive.</p>
- <p style="margin-left=3em">The common parent-pom configures the property
+ <!--p style="margin-left=3em">The common parent-pom configures the property
<code>sourceReleaseAssemblyDescriptor</code> to "multimodule-source-release",
this property value is used by the common Apache POM to pick the
source assembly descriptor from the
- uima-build-resources.</p>
- <p>For binary distributions, done with -distr projects,
- these files come from src/main/readme/. For binary distributions,
- done using single-project parent (add-ons, typically), these files
- are copied from the top level of the project into the archive.</p></td>
+ uima-build-resources.</p-->
+ <p>For PEAR, OSGi, and binary assemblies,
+ these files come from src/main/readme/, the <code>maven-resources-plugin</code>
+ uses the <code>copy-resources</code> goal to copy these.</p></td>
</tr>
<tr>
<td>README.txt</td>
<!-- variants -->
<td/>
- <td><p>For -distr poms, for source distributions, these come from
- same-named files at the top level of the -distr project.
- For binary distributions, the custom assembly specifies where these
- files come from (typically src/main/readme).
- </p>
- <p>For Addon projects, if there is a README at the top level, this
- is copied into both the source and binary distributions, at the top level of the archive.</p>
- </td>
- <td>source-release.zips and binary distribution releases (not in Jars).
- Goes at the top level of archive.
+ <td><p>For PEAR, OSGi, binary assemblies, and source zips distributions, these come from
+ same-named files at the top level of the project doing the creating of the release artifact.
+ </p>
</td>
+ <td>Included in all packagings, except project Jars at the top level of package.</td>
<td>
<p>For source release building, during release (only) (apache-release profile activated)
parent-pom-top configures the assembly plugin for source assemblies to use
the multimodule-source-release in uima-build-resources. This copies
the README file from the top level into the top level of the archive.
</p>
- <p>For binary distributions, the assembly copies the README from src/main/readme/
- or from the top level in the project.</p>
</td>
</tr>
@@ -322,17 +409,14 @@ our svn tree, in a top level directory n
<!-- variants -->
<td/>
<!-- Sources -->
- <td><p>For -distr poms, source for these was in src/main/readme/, but is now
- at the top level (to reduce configuration by following more conventions)</p>
- <p>For (some) Addons, there is a RELEASE_NOTES at the top level, which
- is copied into the source and binary distributions to the top level of the archive.</p>
+ <td><p>At the top level</p>
</td>
<!-- Targets -->
- <td>source-release.zips for some projects and binary distribution releases (not in Jars).
- Goes at the top level of archive.</td>
+ <td>Included in all packagings, except project Jars at the top level of package.</td>
<!-- Method -->
<td>
- <p>During release builds the assembly is configured to copy these from the top
+ <p>During release builds the assembly or maven-resources-plugin
+ is configured to copy these from the top
level of the project to the top level of the archive.
</p>
</td>
@@ -353,7 +437,7 @@ our svn tree, in a top level directory n
<td>This is a computed resource.</td>
<!-- Targets -->
<td>This is generated into the top level of the project, and then goes
- into any archives that are produced, at the top level.</td>
+ into all packagings except OSGi, at the top level.</td>
<!-- Method -->
<td>
<p>The build process runs the maven changes:jira-report plugin to generate this.
@@ -450,9 +534,9 @@ our svn tree, in a top level directory n
<p>If an annotator isn't suitable for PEAR packaging, perhaps because it is inappropriate to have
one pre-done main descriptor, then the annotator can be packaged as a single-project, instead, by
- making the POM's parent parent-pom-single-project.</p>
+ marking the POM's parent parent-pom-single-project.</p>
- <h2>Common conventions for structuring individually releaseable projects</h2>
+ <h2 id="Common conventions individual projects">Common conventions for structuring individually releaseable projects</h2>
<p>Use these conventions to get your annotator properly packaged when you use the parent-pom-annotator or
the parent-pom-single-project as your parent pom:
<ul>
@@ -476,7 +560,7 @@ our svn tree, in a top level directory n
</ul>
</p>
- <h2>Conventions for structuring individual projects released as PEARs</h2>
+ <h2 id="Conventions for PEARs">Conventions for structuring individual projects released as PEARs</h2>
<p>
<ul>
<li>Using the following folders at the top level of your project (which
@@ -514,8 +598,8 @@ our svn tree, in a top level directory n
<ul>
<li>UIMA - the base Java framework</li>
<li>UIMA-AS - the asynchronous scaleout add-on</li>
- <li>UIMA Add-ons - not decided yet, but it's likely we'll just release these as individual projects.
- So there is no add-ons-distr project (yet).</li>
+ <li>UIMA Add-ons - These are released as a collection. Future updates will
+ likely release these individually.</li>
<!--li>UIMA Add-ons - annotators and other add-on components such as the SimpleServer</li-->
<li>UIMACPP - the C++ framework</li>
</ul>
@@ -528,14 +612,20 @@ our svn tree, in a top level directory n
</section>
-<section name="Build resources">
+<section name="Special resources for build">
<p>During the build process, several resources are used, and are built into Maven Artifact Jars with
- Maven coordinates:
+ Maven coordinates. These projects are in the <code>build</code> section of SVN.
<ul>
- <li>uima-jar-resource-bundle - this is the standard License Notice and Dependencies from the
+ <li>uima-build-resources - this contains various resources used in the build process
+ <ul>
+ <li>the standard License Notice and Dependencies from the
Apache common parent pom, except it allows adding post-Notice text. We use this when
- we need to include the IBM Copyright notice, moved here from donated code from IBM.
- This also has an override for the multi-module source release assembly.</li>
+ we need to include the IBM Copyright notice, moved here from donated code from IBM.</li>
+ <li>an override for the multi-module source release assembly</li>
+ <li>the binary assembly descriptor for single-projects.</li>
+ <li>common specification for the titlepage of docbooks</li>
+ </ul>
+ </li>
<li>uima-docbook-olink - this is the shared
<a target="_blank" href="dev-docbook.html#Cross Referencing among UIMA Docbooks">olink</a> data.
This project's source contains the
@@ -544,9 +634,7 @@ our svn tree, in a top level directory n
This artifact is not released, it always stays at 1-SNAPSHOT level, but can be deployed
to the snapshot repository for sharing with others.
</li>
- <li>uima-docbook-resource-bundle - holds common information needed by docbook builds, including
- the specification for the titlepage.</li>
- <li>uima-assembly-single-project - holds the binary assembly descriptor for single-projects.</li>
+
</ul></p>
<p>There is also one custom Maven plugin (uima-build-helper-maven-plugin)
@@ -564,5 +652,31 @@ our svn tree, in a top level directory n
</p>
</section>
+ <section name="Lifecycle for building addons">
+ <p>Addon projects have multiple binary build artifacts:
+ <ul>
+ <li>binary assembly for the individual addon</li>
+ <li>binary assembly for aggregate of all the addons</li>
+ <li>PEAR packaging</li>
+ <li>OSGi packaging</li>
+ </ul>
+ </p>
+
+ <p>Since these have many common parts, we use the maven lifecycle to order building of shared
+ common things ahead of their use:
+ <ul>
+ <li>package phase: build JARs, docbooks, etc.</li>
+ <li>pre-integration-test phase: this is the first phase after <code>package</code>, and is
+ used to copy the Jar and docbook processing results to a common directory structure (base-bin).</li>
+ <li>integration-test phase: this is the 2nd phas after <code>package</code>, and is
+ used to copy the common things from base-bin to places for building the PEAR and OSGi artifacts.
+ It is also used for running the packaging steps sequentially, after the copy, for the PEAR, OSGi,
+ and single project assemblies.</li>
+ <li>post-integration-test phase: this is used to mark the generated PEAR file for "attachment"
+ using the maven-build-helper, so it gets deployed to the maven repositories.</li>
+ </ul>
+ </p>
+
+ </section>
</body>
</document>
\ No newline at end of file