Google Git
Sign in
apache / uima-site / ae4bf94d1ce1ffde6303a4333f17c60c9898a0a9 / . / docs / maven-design.html
blob: c392b32de18fb4b8b50ef8506fed4df701ae0161 [file] [log] [blame]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "https://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 - How we use Maven for building</title>
<!-- Begin Cookie Consent plugin by Silktide - https://silktide.com/cookieconsent -->
<!-- Commented out because implied consent is not compatible with GDPR -->
<!--
<script type="text/javascript">
window.cookieconsent_options = {"message":"This website uses cookies to ensure you get the best experience on our website","dismiss":"Got it!","learnMore":"More info","link":"https://uima.apache.org/privacy-policy.html","theme":"dark-bottom"};
</script>
<script type="text/javascript" src="/cookieconsent2/cookieconsent.min.js"></script>
-->
<!-- End Cookie Consent plugin -->
<!-- Begin Google Analytics -->
<!-- Commented out because GA requires consent according to GDPR -->
<!--
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-70846351-1', 'auto');
ga('set', 'anonymizeIp', true);
ga('send', 'pageview');
</script>
-->
<!-- End Google Analytics -->
</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_banner2tlpTm.png" alt="UIMA project logo" border="0"/>
</a>
</td>
<td align='CENTER'>
<div class="pageBanner">How we use Maven for building</div>
</td>
<td align='RIGHT'>
<a href="https://www.apache.org">
<img src="./images/asf-logo-on-white-smallTm.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="https://www.google.com/search">
Search the site
<input type="text" name="q" size="25" maxlength="255" value="" />
<input type="hidden" name="sitesearch" value="https://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>
<div class="navBarItem"> <a href="./publications.html">Publications</a>
</div>
<br style="line-height: .5em"/>
<div class="navBarItem"> <a href="https://issues.apache.org/jira/browse/uima" target="_blank" rel="noopener">Issue tracker <img src="images/offsitelink.png"/></a>
</div>
<div class="navBarItem"> <a href="https://cwiki.apache.org/confluence/display/UIMA/" target="_blank" rel="noopener">Wiki <img src="images/offsitelink.png"/></a>
</div>
<br style="line-height: .5em"/>
<div class="navBarItem"> <a href="https://cwiki.apache.org/confluence/display/UIMA/Powered+by+Apache+UIMA" target="_blank" rel="noopener">Powered By UIMA <img src="images/offsitelink.png"/></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="./mail-lists.html">Mailing Lists</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">Scaleout Frameworks</div>
</div>
<div class="navBar">
<div class="navBarItem"> <a href="./doc-uimaas-what.html">UIMA-AS</a>
</div>
<div class="navBarItem"> <a href="./doc-uimaducc-whatitam.html">UIMA-DUCC</a>
</div>
<div class="navBarItem"> <a href="./doc-uimaducc-demo.html">..Demo Page</a>
</div>
<div class="navBarItem"> <a href="http://uima-ducc-demo.apache.org:42133" target="_blank" rel="noopener">..Demo Live <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="./sandbox.html#uima-addons-annotators">Annotators</a>
</div>
<div class="navBarItem"> <a href="./toolsServers.html">Tools & Servers</a>
</div>
<div class="navBarItem"> <a href="./sandbox.html">Addons and Sandbox</a>
</div>
<div class="navBarItem"> <a href="./ruta.html">UIMA Ruta</a>
</div>
<div class="navBarItem"> <a href="./uimafit.html">uimaFIT</a>
</div>
<div class="navBarItem"> <a href="./external-resources.html">External Resources</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="./release.html">Doing a UIMA release</a>
</div>
<div class="navBarItem"> <a href="https://www.apache.org/security/committers.html" target="_blank" rel="noopener">Doing a CVE (Apache) <img src="images/offsitelink.png"/></a>
</div>
<div class="navBarItem"> <a href="./eclipse-update-site.html">Eclipse Update Sites</a>
</div>
<div class="navBarItem"> <a href="./git.html">GIT</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 class="navBarItem"> <a href="./updating-website.html">Updating this Website</a>
</div>
</div>
<br/>
<div class="navBarItem"> <div class="navPartHeading">Events and Conferences</div>
</div>
<div class="navBar">
<div class="navBarItem"> <a href="./coling14.html">COLING 2014</a>
</div>
<div class="navBarItem"> <a href="./gscl13.html">GSCL 2013</a>
</div>
<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="https://www.apache.org/licenses/" target="_blank" rel="noopener">License <img src="images/offsitelink.png"/></a>
</div>
<div class="navBarItem"> <a href="https://www.apache.org/foundation/thanks.html" target="_blank" rel="noopener">ASF Sponsors <img src="images/offsitelink.png"/></a>
</div>
<div class="navBarItem"> <a href="https://www.apache.org/foundation/sponsorship.html" target="_blank" rel="noopener">ASF Sponsorship <img src="images/offsitelink.png"/></a>
</div>
<div class="navBarItem"> <a href="./security_report">Security</a>
</div>
</div>
</div>
</td>
<td width="80%" align="left" valign="top">
<div class="sectionTable">
<table class="sectionTable">
<tr><td>
<a name="Maven use for Apache UIMA builds"><h1><img src="images/UIMA_4sq50tightCropSolid.png"/>&nbsp;Maven use for Apache UIMA builds</h1></a>
</td></tr>
<tr><td>
<blockquote class="sectionBody">
<p>This is developer information, mostly. It documents how we are using Maven for
building the various parts of UIMA.</p>
<p>We follow Apache conventions for releasing Maven based projects
(all of ours except the
UIMA C++ enablement layer), using Nexus, as documented here:
<a target="_blank" rel="noopener" href="https://www.apache.org/dev/publishing-maven-artifacts.html">
https://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
</a></li>
<li><a href='#POM Conventions'>
POM Conventions
</a></li>
<li><a href='#Our POM hierarchy'>
Our 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, signing, checksums'>
Release artifacts, signing, checksums
</a></li>
<li><a href='#Handling Documentation'>
Handling Documentation
</a></li>
<li><a href='#Packaging Individual Projects'>
Packaging Individual Projects
</a></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>
<a name="Nexus">
<h2>Nexus
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>Apache runs a version of <a target="_blank" rel="noopener" href="https://nexus.sonatype.org/">Nexus</a>, a
repository "manager". Nexus has been set up to support releasing Maven artifacts. It allows
Maven's release plugin to think it is actually "releasing" and deploying to a Maven repository, when
in actuality, the release configuration specifies deploying to the "staging" part of the Apache
Nexus instance. Once the release is verified and voted on, it can then be transferred up to
Maven central repository with a few clicks on the website.</p>
<p>We are currently using the
<a href="https://repo1.maven.org/maven2/org/apache/apache/7/apache-7.pom" target="_blank" rel="noopener">
Apache common parent POM</a>
which supports deployment to
this Apache Nexus repository, for staging and release.
It also supplies many of the standard items needed for all Apache projects.</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="POM Conventions">
<h2>POM Conventions
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>We follow the conventions regarding the layout of the POM as specified
<a target="_blank" rel="noopener" href="https://maven.apache.org/developers/conventions/code.html#POM_Code_Convention">
here</a>.</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Our POM hierarchy">
<h2>Our POM hierarchy
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>POMs have two kinds of hierarchy:
<ol>
<li>The main one is used for factoring out common
things and arranges POMs in a parent-child hierarchy, by having the child
identify the parent POM.
</li>
<li>
The other kind is aggregation - POMs which specify sub-modules
for purposes of building multi-module things, and releasing them all at once.
</li>
</ol>
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 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
our svn tree, in a top level directory named "build".</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Selecting build alternatives based on the project">
<h2>Selecting build alternatives based on the project
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>The shared UIMA-wide common parent POM supports many different
kinds of builds. For instance, some projects use Docbook,
some projects are "distribution" projects that serve to build
our binary distribution, some projects build PEAR artifacts
(e.g., many of our Addons projects), etc.</p>
<p>Common support for each of these kinds of project builds is
kept in the common parent POM, but in a profile, which is
only activated for that kind of project. The activation
is actually done by detecting the presence of a file, named
by convention <code>marker-file-identifying-xxxxxxxx</code>,
where the xxxxxxxx is a particular name. These are 0-length
files put at the top level of projects that need a particular
profile activation in the common Parent pom.
</p>
<p style="margin-left=3em">An exception to this is the profile
for processing Docbooks, which instead is activated by the
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-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>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="POM style">
<h2>POM style
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>When writing a new POM, it is best to start with an existing POM for a similar
kind of project, and derive the new POM from that. Some points:
<ul>
<li><p>POMs contain a <code>&lt;url&gt;</code> element, which is supposed to
point to the UIMA website page for this artifact (or the main UIMA page).
If a POM doesn't have this element, it will inherit one from its parent
but Maven will assume (usually incorrectly in our case)
that the url is the parent url value followed by "/" and
this POMs artifactId.</p>
<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 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.
Maven 3
will complain if you use properties here, and the release mechanism for maven
manipulates these values (removing SNAPSHOT, incrementing things, etc.)</li>
<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>In the <code>build</code> section, the <code>&lt;groupId&gt;</code> for
standard maven plugins is omitted.</li>
</ul>
</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Release artifacts, signing, checksums">
<h2>Release artifacts, signing, checksums
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>We follow the standard release process for Maven-based artifacts at Apache,
documented <a target="_blank" rel="noopener" href="https://www.apache.org/dev/publishing-maven-artifacts.html">here.</a></p>
<p>There are two places artifacts go to:</p>
<ol>
<li>Apache's mirror distribution system</li>
<li>Maven "central" for maven-findable artifacts (typically JARs)</li>
</ol>
<p>Apache's mirror distribution system is used to distribute the source-release.zip and
any binary convenience packages.
</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>javadocs.jar</li>
</ul>
<p>The source-release.zip file is a special artifact, like the sources.jar, 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 built only at the top (root) level and are not "attached" so it is
not uploaded to maven for distribution, but instead is distributed via Apache's mirror system.
</p>
<p>
The release process happens when the commands <code>mvn release:prepare</code> followed by
<code>mvn release:perform</code> are executed. The release plugin is set up by the common
Apache parent Pom to specify the <code>apache-release</code> profile. It is this profile
being selected that causes (among many other things) the sources.jar and
source-release.zip artifacts to be built.
You can debug this process without doing a release, by adding the parameter
<code>-Papache-release</code> to the non-release Maven build commands.
</p>
<p>For apache-releases (triggered with the apache-release profile), all artifacts
get signed with gpg signatures, as well as with .sha512 checksums.
These are created during the build for the top level project, when
the apache-release profile is specified, or when the mvn release plugin is run.
Most of the signatures happen because of the gpg plugin and the
checsum-maven-plugin, but the source-release.zip artifact has its own
special antrun task since it's not attached.
</p>
<h2>LICENSE and NOTICE files</h2>
<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>
<li>Eclipse Features
<ul>
<li>Features have their own special Eclipse-style form for licenses</li>
<li>Boilerplate for these are kept in a common spot in the uima-build-resources project,
in the subdirectory: licenses-eclipse-plugs-features.
There are two files here. One is the boilerplate license, in
uima-eclipse-user-agreement.html (a text copy is also embedded in the features.properties).
The second file is a boilerplate features.properties.</li>
<li>Both of these files should be copied to the top level of feature project(s), and
the feature.properties should be edited to have the right values for the particular feature.</li>
</ul>
</li>
</ul>
</p>
<h3>Three kinds of LICENSE/NOTICE files</h3>
<p>There are typically three versions of these files, corresponding to source (only)
distributions, other distributions which include "dependent" artifacts, which
may have their own separate license and notice information, and a special one for
Eclipse Features. 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>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>
<h2>Standard Artifacts</h2>
<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
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
(we use this to add the IBM Copyright formerly
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
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>
<li>adding this information as part of generated assemblies - these files are copied to the top
level (above any project).</li>
</ul>
</p>
<p>
The remote-resources-plugin adds a &lt;resource&gt; entry to the maven in-memory model &lt;resources&gt;
element that specifies that the files in target/maven-shared-archive-resources/ be copied to
target/classes. (You can see this by running a mvn package step with the -X parameter.)
This is what the remote-resources documentation means when it says:
"... the resources are injected into the current (in-memory) Maven project,
making them available to the process-resources phase."
</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 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 because it is
(usually) only distributing Apache-authored source; while the
binary distribution often distributes additional components that are licensed under other
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 <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 instance 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>
<h2>Eclipse Features and Plugins</h2>
<p>The license and notice section for Eclipse plugins follows the conventions used for
other Jars. For Eclipse Features, there is a boilerplate license used for all Features, which, in turn, refers to specific
other embedded Licenses and Notices. The boilerplate becomes part of the Feature jar.
</p>
<p>When setting up a new Eclipse Feature, developers need to manually copy the latest boilerplate
features.properties and uima-eclipse-user-agreement.html files from the uima-build-resources project
into their feature project top-level directory.
They need to then modify the values of the following properties for their feature:
<ul><li>featureName</li><li>description</li></ul>
</p>
<p>The build adds these files to the resource set when building the jar.
</p>
<h2>Summary: License and Notices</h2>
<p>This next table summarizes the packaging artifacts and how and where they are
located and added during the build process.</p>
<table class="downloads"> <!-- class is just to format the table like our downloads tables -->
<tr>
<th>Artifacts</th>
<th>Variants</th>
<th>Sources</th>
<th>Targets</th>
<th>Methods</th>
</tr>
<tr>
<td><p>LICENSE, NOTICE, DEPENDENCIES.</p></td>
<!-- variants -->
<td><p>Standard, for source distribution</p><br /><br />
<p>Alternate: has extra Notice element used for copyrights moved to Notice file.</p><br /><br />
<p>Alternate2: for binary assemblies, the LICENSE and NOTICE
are customized for each binary assembly.</p><br /><br />
<p>Eclipse Features</p>
</td>
<!-- 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>&lt;postNoticeText&gt;</code>in the build POM.
For many cases, the additional copyright notice is for
IBM contributed code, which can be included using
<code>&lt;postNoticeText&gt;${ibmNoticeText}&lt;/postNoticeText&gt;</code>.</p>
<p>For binary distributions, comes from src/main/readme/
</p>
<p>For Eclipse Features: developer manually copies features.properties and
uima-eclipse-user-agreement.html from uima-build-resources project's folder
licenses-eclipse-plugs-features, to the Eclipse feature top level. Developer
manually edits two properties in features.properties - the feature name and description.</p>
</td>
<!-- Targets -->
<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>
<p>Eclipse Features: filter.properties and uima-eclipse-user-agreement.html get included in Jar at top level</p>
</td>
<!-- Method -->
<td><p>org.apache.uima:parent-pom configures the remote-resources plugin
to copy the standard LICENSE/NOTICE/DEPENDENCIES into
target/maven-shared-archive-resources/META-INF/
directory. The remote-resources plugin addes this dir to the
the list of standard resources the resources:resources goal copies into
target/classes.
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
<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 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>
<p>For Eclipse features, a build &lt;resource&gt; element addes the 2 files.</p>
</tr>
<tr>
<td>README.txt</td>
<!-- variants -->
<td />
<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>
</td>
</tr>
<tr>
<!-- artifact -->
<td><p>RELEASE_NOTES.html</p>
<p>Each release can include release notes
describing the main changes for the release.</p></td>
<!-- variants -->
<td />
<!-- Sources -->
<td><p>At the top level</p>
</td>
<!-- Targets -->
<td>Included in all packagings, except project Jars at the top level of package.</td>
<!-- Method -->
<td>
<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>
</tr>
<tr>
<!-- artifact -->
<td><p>issuesFixed</p>
<p>Each release can include a top-level directory called issuesFixed,
which has a file jira-report.html</p>
<p>This is generated
automatically when a release is built.</p>
<p>It contains the set of fixed/resolved Jiras that correspond to this release.
</p></td>
<!-- variants -->
<td>none</td>
<!-- Sources -->
<td>This is a computed resource.</td>
<!-- Targets -->
<td>This is generated into the top level of the project, and then goes
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.
The release manager must insure the property specifying the Jira(s)
versions included in this release is properly specified, to enable the right
issues to be included in the report.
</p>
</td>
</tr>
</table>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Handling Documentation">
<h2>Handling Documentation
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>We have several kinds of documentation:</p>
<ul>
<li>Javadocs</li>
<li>Docbook</li>
<li>UIMA Website (Anakia)</li>
</ul>
<p>We use Docbook style for much of our documentation,
the main exception being our website, which uses Anakia.
See the <a href="dev-docbook.html">how to use docbook</a> page for information
about how to write Docbook style documentation, and how it is processed during building.</p>
<p>Docbooks are built, if present, during the normal lifecycle.</p>
<p>Javadocs are built during the release process for Java sources packaged as a Jar.
In addition, some distribution projects collect things from multiple projects and build
explicitly, larger Javadoc sets. (e.g., uimaj-distr).
</p>
<p>For the web site, documentation is kept in the SVN "site" top level directory. Within that project,
the sources are in the <code>xdocs</code> directory; anything there is expected to be written using Anakia
markup, and the <code>build.xml</code> ant script is used to transform these into corresponding html
files in the <code>docs</code> directory.</p>
<p>Normally, all website-ready content (not needing Anakia processing)
is kept in SVN in the <code>uima/site/trunk/uima-website/docs</code> directory;
this directory is manually checked out into the right spot on <code>people.apache.org</code>, the sources
are updated.
Large generated documents are put directly onto people.apache.org in the directory
/www/uima.apache.org/d/, and not checked into SVN. The files kept here include
the javadocs and the generated docbook html and pdf files.
This avoids using SVN for large generated files. This satisfies the
<a href="https://apache.org/dev/project-site.html" target="_blank" rel="noopener">requirements</a>
for Apache websites.</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Packaging Individual Projects">
<h2>Packaging Individual Projects
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>
The UIMA Project, in addition to the main frameworks (the UIMA SDK and the UIMA-AS addon),
has Annotators and other components and tools
(such as the SimpleServer) that it releases. These in the past have been released as a big
assembly we called the Addons or Sandbox, but now are are being supported also as individual items.
</p>
<p>
Two kinds of packaging for these are available, chosen by specifying one of the following parent-poms:
<ul><li>parent-pom-annotator - this packages things as a PEAR</li>
<li>parent-pom-single-project - this packages things as a tar / zip file having a lib/ directory
with the generated Jar and dependencies (see below).</li></ul>
</p>
<p>
The individual Annotators are mostly packaged as
<a href="d/uimaj-current/references/references.html#ugr.ref.pear">
PEAR</a> files, which are the UIMA standard for annotator component packaging and distribution.
The Pear is generated using the PearPackagingMavenPlugin, which generates automatically a
conventional Pear Installation Descriptor, from the information in the project.
The PEAR artifact is generated in addition to Jar of the code, and includes
other items such as the generated documentation, data, and a lib/ directory with other Jars
needed for the PEAR to operate. This PEAR is the packaged equivalent of a binary distribution
artifact produced for the main framework, and comes with a license and notice that
covers any included libraries. Generated PEARs are included in the artifacts that are managed by
Maven, and are available in the Maven repository system.
</p>
<p class="note">
The PEAR internal folder "src" is not used by components here; the source is instead available
via the standard Maven source directory conventions.
</p>
<p>
PEARs must have a "main" descriptor, which is the one normally used to configure and run
the annotator. When using the parent-pom-annotator to indicate PEAR packaging,
you must include a property called <code>
&lt;pearMainDescriptor&gt;</code> in the Annotator's POM,
whose value is the path from the project base directory
identifying the main descriptor. For example, if the folder "desc" was at the root of your project, the
value might be something like "desc/my-main-descriptor.xml".
</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
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>
<li>Use &lt;package&gt;jar&lt;/package&gt; (which is the default, so it should be omitted), if there
is a Jar that should be built (as is usually the case). This will cause the main
annotator Jar to be built, including any resources (plus the top-level desc folder, if it exists),
as normal.</li>
<li>Create the required License, Notice, and optional Readme, and Release Notes files
in the project directory at the top level; these will be included in the
PEAR or simple project binary assembly at the top level.
The License and Notice files should be for the entire project, including
all third-party Jars etc. being distributed.
<p style="margin-left: 2em">The generated Jar, which only has Apache-developed code,
will have the normal Apache License and Notice files.</p></li>
<li>Dependencies: those marked with scope "compile" (the default) or "runtime"
are copied to the PEAR or single-project's lib/ directory. To keep a dependency needed for compiling
from being included in the lib/, give it a scope of "provided".
<p class="note">You may use the dependencies <code>&lt;exclusions&gt;</code> element to control
transitive dependencies.</p>
</li>
</ul>
</p>
<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
are the folders used in the "conventional" PEAR layout,
causes the contents of these folders to be added to the corresponding files in the PEAR or binary zip/tar:
<ul>
<li>desc - for descriptiors, including the main descriptor</li>
<li>bin - (optional) for extra executables</li>
<li>lib - (optional) for libraries (not being included via the Maven dependencies mechanism)</li>
<li>doc - (optional) not normally used, but can have additional user-ready documentation</li>
<li>data - (optional) for arbitrary data</li>
<li>resources - (optional) not normally used, but can have additional data which should be on the classpath</li>
<li>conf - (optional) for extra configuration files</li>
<li>src - not-used - Maven conventions for src directories are used instead</li>
</ul>
<p>The following Maven conventional information will be added in the generated PEAR:
<ul>
<li>lib - dependencies with scope "compile" or "runtime" are resolved from maven repositories and added to the lib/</li>
<li>doc - docbook sources under src/docbook are processed and the html and pdf forms are added</li>
<li>Maven resources - (not the top level resources directory described above)
are by convention included in the Jar, and are not included in this folder</li>
</ul>
</p>
</li>
</ul>
</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Building Assemblies for Distribution">
<h2>Building Assemblies for Distribution
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>The normal operation of Maven is concerned with the building of individual modules. Each module
when built produces maven artifacts in repositories (your local repository, or perhaps uploaded
to a snapshot or staging repository).</p>
<p>When releases are done, additional artifacts are constructed using the distribution assemblies.
We have these for
<ul>
<li>UIMA - the base Java framework</li>
<li>UIMA-AS - the asynchronous scaleout add-on</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>
</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Special resources for build">
<h2>Special resources for build
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>During the build process, several resources are used, and are built into Maven Artifact Jars with
Maven coordinates. These projects are in the <code>build</code> section of SVN.
<ul>
<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.</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" rel="noopener" href="dev-docbook.html#Cross Referencing among UIMA Docbooks">olink</a> data.
This project's source contains the
information about the UIMA Bookshelf - the set of books that can cross-reference each other,
and how they're laid out (current layout - they all are subitems of one common directory).
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>
</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.
This is used, for instance, in the common docbook frontmatter to indicate when the book was
built.</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Using the Release Audit Tool (RAT)">
<h2>Using the Release Audit Tool (RAT)
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<p>From parent-pom version 2 and onwards,
RAT is run automatically, but only when the Maven profile "apache-release" is activated.
Projects that override the default RAT exclusions must include all things that need to be excluded,
and put this configuration into their POM in the "pluginManagement" section; see the project uimaj-core
for an example.
</p>
</blockquote>
</td></tr>
</table>
<table class="subsectionTable">
<tr><td>
<a name="Lifecycle for building addons">
<h2>Lifecycle for building addons
</h2>
</a>
</td></tr>
<tr><td>
<blockquote class="subsectionBody">
<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>
</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 &#169; 2006-2013, 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>