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 2010/11/22 21:57:34 UTC
svn commit: r1037885 [3/3] - in /uima/site/trunk/uima-website: docs/
docs/staging/ xdocs/ xdocs/stylesheets/
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=1037885&r1=1037884&r2=1037885&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/maven-design.xml (original)
+++ uima/site/trunk/uima-website/xdocs/maven-design.xml Mon Nov 22 20:57:31 2010
@@ -33,15 +33,13 @@ 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
+ UIMA C++ enablement layer), using Nexus, as documented here:
<a target="_blank"
- href="http://www.apache.org/dev/publishing-maven-artifacts.html">here</a>.</p>
-
-<p>It covers how we use Maven for building Version: 2.3.1 and onwards.</p>
- <p>A transition to Maven 3 is occurring in 2010. Maven 3 corrects many issues, including
- one we rely on, regarding inheriting of profiles, so we pre-req Maven 3.0.
- </p>
+ 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>
+
<subsection name="Nexus">
<p>Apache runs a version of <a target="_blank" href="http://nexus.sonatype.org/">Nexus</a>, a
@@ -52,14 +50,14 @@ building the various parts of UIMA.</p>
Maven central repository with a few clicks on the website.</p>
<p>We are currently using the
- <a href="http://repo2.maven.org/maven2/org/apache/apache/7/apache-7.pom" target="_blank">
+ <a href="http://repo1.maven.org/maven2/org/apache/apache/7/apache-7.pom" target="_blank">
Apache common parent POM</a>
which supports deployment to
-this Apache Nexus repository, for staging and release. You can see that POM
-<a href="http://repo1.maven.org/maven2/org/apache/apache/7/apache-7.pom" target="_blank">
- here</a>. It also supplies many of the standard items needed for all Apache projects.</p>
+this Apache Nexus repository, for staging and release.
+It also supplies many of the standard items needed for all Apache projects.</p>
</subsection>
</section>
+
<section name="POM Conventions">
<p>We follow the conventions regarding the layout of the POM as specified
<a target="_blank"
@@ -83,46 +81,13 @@ 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>An exception to this is the
-parent-poms hierarchy; here, each parent-pom has a %lt;modules> section which
-lists the poms which in turn, have this pom as their parent. This allows the
-release plugin to support releasing a pom, together with all of the build parent poms that are
-its children (recursively), together. This is needed because the poms must all have their
-version numbers adjusted for the release (dropping the -SNAPSHOT, etc.) which
-the release plugin does.</p>
-
-<p>Our parent poms are kept in a folder, "parent-poms", under a top level SCM node called "build", which holds things
- needed for building, but which are not part of normal uima release distributions.
- Aggregation POMs are kept within the SCM parent directory containing those modules being aggregated,
- in a "flat hierarchy" structure.</p>
-
- <subsection name="Parent Pom Hierarchy">
- <p>Parent pom names start with parent-pom-:</p>
-<pre>
-parent-pom-top
-
- parent-pom-docbook
- - enables docbook processing (if docbook source is present)
- parent-pom-ibm-notice
- - same as top but adds IBM notice
-
- parent-pom-eclipse-plugins
-
- parent-pom-eclipse-plugins-ibm-notice
- - same as above but adds IBM notice
-
- parent-pom-annotator
- - used to build PEAR packaged single-project annotators
-
- parent-pom-single-project
- - used to build non-PEAR packaged single-project annotators
-
- parent-pom-distr
- - used to build Binary Aggregate distributions
- (UIMA SDK and UIMA-AS)
-</pre>
-</subsection>
+<p>The UIMA Project as 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>
</section>
<section name="POM style">
@@ -161,14 +126,12 @@ parent-pom-top
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.
+ Maven deployment to repositories.</p>
<ul>
<li>
sources.jar - holds the source files - this is for IDEs that want to refer to the source
</li>
- <li>
- javadoc.jar - (For Java sourced artifacts, only)
- </li>
+
<li>
source-release.zip - this is the same as the sources, but includes all other files
(such as the pom.xml) not under the /src
@@ -177,20 +140,24 @@ parent-pom-top
should be "buildable" by doing "mvn install", etc. in the unzipped directory.
</li>
</ul>
- The release process happens when the command <code>mvn release:prepare</code> or
- <code>mvn release:perform</code> is executed. The release plugin is set up by the common
- Apache super-Pom to specify the <code>apache-release</code> profile. It is this profile
- being selected that causes (among many other things) the sources.jar, javadoc.jar and
+ <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.
</p>
<subsection name="Standard Artifacts">
- <p>The release process includes standard artifacts in standard places. The Maven remote-resources-plugin
- is used to get these resources from a special a UIMA build artifact (uima-jar-resource-bundle),
+ <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:
- <ul><li>The DEPENDENCIES file is generated from the transitive closure of the dependencies in the POM.</li>
- <li>The NOTICES file is augmented with additional text (we use this to add the IBM Copyright formerly
+ <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>
@@ -203,7 +170,8 @@ parent-pom-top
</ul>
</p>
- <p><b><u>Overriding on a per-project basis:</u></b> Files that the remote-resources-plugin obtains and places
+ <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>
@@ -223,6 +191,7 @@ parent-pom-top
<p>This next table summarizes the packaging artifacts and how and where they are
located and added during the build process.</p>
+ <p class="note">This table is out of date and needs updating (Nov 2010).</p>
<table class="downloads">
<tr>
@@ -324,25 +293,21 @@ parent-pom-top
<p>Each release can include a top-level directory called issuesFixed,
which has a file jira-report.html</p>
<p>This is generated
- by the release manager using a top level command when a release is being
- contemplated.</p>
+ 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, computed when the top level command is run.</td>
+ <td>This is a computed resource.</td>
<!-- Targets -->
<td>The directory goes at the top level of archive</td>
<!-- Method -->
<td>
- <p>A special command is run by the release manager to create or update this.
- The command is</p>
- <p><code>mvn -N -DjiraVersion=xxxxxx changes:jira-report</code></p>
- <p>
- run in the top level directory being released. xxxxxx is the <b>internal</b>
- version id used by Jira for the particular version being released - see
- <a href="release.html">release.html</a> for how to obtain this.
+ <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>
Modified: uima/site/trunk/uima-website/xdocs/one-time-setup.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/one-time-setup.xml?rev=1037885&r1=1037884&r2=1037885&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/one-time-setup.xml (original)
+++ uima/site/trunk/uima-website/xdocs/one-time-setup.xml Mon Nov 22 20:57:31 2010
@@ -48,6 +48,8 @@ under the License.
as the one from Tigris.org.</p>
<p>If you are using an IDE, you should obtain the SVN client for that IDE.</p>
+ <p>See <a href="svn.html">svn.html</a> for further details about accessing the source,
+ including accomodating firewalls.</p>
</section>
<section name="One time setup for Maven" id="maven-setup">
Modified: uima/site/trunk/uima-website/xdocs/stylesheets/project.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/stylesheets/project.xml?rev=1037885&r1=1037884&r2=1037885&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/stylesheets/project.xml (original)
+++ uima/site/trunk/uima-website/xdocs/stylesheets/project.xml Mon Nov 22 20:57:31 2010
@@ -2,7 +2,6 @@
<project name="Apache UIMA Project"
href="http://uima.apache.org/">
- <incubator name="Apache Incubator" href="http://incubator.apache.org/"/>
<title>Apache UIMA</title>
<logo href="/images/asf-logo-on-white-small.png">Apache UIMA</logo>
<projectLogo href="/images/UIMA_banner2tlp.png">UIMA project logo</projectLogo>
@@ -43,15 +42,16 @@
</item>
<item name="Development">
+ <item name="Quick Start: building" href="/dev-quick.html"/>
+ <item name="Building from Source" href="/building-uima.html"/>
<item name="One-time setups" href="/one-time-setup.html"/>
<item name="Source Code" href="/svn.html"/>
- <item name="Maven Use" href="/maven-design.html"/>
- <item name="Building from Source" href="/building-uima.html"/>
<item name="Creating a Distribution" href="/distribution.html"/>
<item name="Doing a UIMA release" href="/release.html"/>
<item name="Code Conventions" href="/codeConventions.html"/>
<item name="UIMA Specification (OASIS)" href="/uima-specification.html"/>
<item name="Project Team" href="/team-list.html"/>
+ <item name="Maven Use" href="/maven-design.html"/>
</item>
<item name="Events and Conferences" >
Modified: uima/site/trunk/uima-website/xdocs/svn.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/svn.xml?rev=1037885&r1=1037884&r2=1037885&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/svn.xml (original)
+++ uima/site/trunk/uima-website/xdocs/svn.xml Mon Nov 22 20:57:31 2010
@@ -54,7 +54,8 @@ under the License.
<li><a href="#committing.changes">Committing changes to subversion</a></li>
</ul>
<br></br>
- </li>
+ </li>
+ <!--
<li><a href="#building.with.maven">Building UIMA from Source</a>
<ul>
<li><a href="#building.command.line">Building from the command line</a></li>
@@ -62,8 +63,9 @@ under the License.
<li><a href="#test.failure">What to do if the tests fail</a></li>
<li><a href="#build.distribution">How to build the full Apache UIMA distribution</a></li>
<li><a href="#building.docbooks">Building uima-docbooks</a></li>
- </ul>
+ </ul>
</li>
+ -->
</ul>
</p>
</section>
@@ -135,14 +137,13 @@ below for more information.
<p>For those users who are behind a corporate firewall which is
blocking http access to the Subversion repository, you can try to access it
via HTTPS: </p>
-<longquote><code>% svn checkout \<br/>
- https://svn.apache.org/repos/asf/uima/uimaj/trunk</code></longquote>
+<longquote><code>% svn checkout https://svn.apache.org/repos/asf/uima/uimaj/trunk</code></longquote>
</subsection>
<subsection name="Access through a proxy" id="access.proxy">
<p>The Subversion client can go through a proxy, if you configure it
to do so. First, edit your "servers" configuration file to indicate which
-proxy to use. The files location depends on your operating system.
+proxy to use. The location of this configuration file depends on your operating system.
On Linux or Unix it is located in the directory "~/.subversion".
On Windows it is in "%APPDATA%\Subversion". (Try "echo %APPDATA%",
note this is a hidden directory.) </p>
@@ -164,15 +165,11 @@ http-proxy-port = 3128
<p>Everyone can access the Apache UIMA Subversion repository via HTTPS.
Apache UIMA Committers must checkout the Subversion repository
-via HTTPS, in order to be able to check in changes.
+via HTTPS (not HTTP), in order to be able to check in changes.
</p>
-<longquote><code>% svn checkout \<br/>
- https://svn.apache.org/repos/asf/uima/uimaj/trunk</code></longquote>
+<longquote><code>% svn checkout https://svn.apache.org/repos/asf/uima/uimaj/trunk</code></longquote>
</subsection>
-<subsection name="Checking Out Code using Eclipse" id="checkout.using.eclipse">
-<p>See <a href="building-uima.html#checkout.using.eclipse">Building UIMA - checkout using Eclipse</a>.</p>
-</subsection>
</section>
<section name="Submitting Code Changes" id="submit.code.changes">
@@ -248,6 +245,7 @@ http://jira.atlassian.com/browse/SVN-37<
</subsection>
</section>
+<!--
<section name="Building UIMA">
<subsection name="Building UIMA from Source" id="building.with.maven">
<p>
@@ -261,81 +259,7 @@ http://jira.atlassian.com/browse/SVN-37<
page.</li></ol>
</p>
-</subsection>
-
-<subsection name="Building from the Command Line" id="building.command.line">
- <p>
- See <a href="building-uima.html#building.command.line.one">Building one project from the command line</a>, and
- <a href="building-uima.html#building.command.line.group">Building all the projects for a major component from the command line</a>.
- </p>
-</subsection>
-
-<subsection name="Building from Eclipse" id="building.eclipse">
- <p>With m2eclipse plugin, you can right-click any maven project, and select <code>Run -> maven commands</code> to do maven runs. Furthermore, you can
- save run configurations you build using <code>Run -> Run As ... -> Maven build ...</code>; these become launchable using the standard Eclipse run menus.
- </p>
-
- <p>Within a project, you can run the unit tests in Eclipse by right-clicking on a folder (for example
- <code>uimaj-core/src/test/java</code>) and selecting <code>Run As -> JUnit Test</code>. This will run all tests
- under that folder.</p>
- <!--
- <ol>
- <li><p>First, follow all the steps under "Building from the command line, above." You
- will only need to do this once.</p></li>
- <li><p>(Optional) If you want a new workspace for the maven work, start Eclipse and create a new workspace. </p></li>
- <li><p>In a command window, execute
- <blockquote>
- <pre>
-mvn -Declipse.workspace=<eclipse workspace dir> \
- eclipse:add-maven-repo</pre>
- </blockquote>
- This adds a maven repository to your machine (On Windows, under documents & settings / .m2 /
- repository), and sets up an Eclipse Java Build Path variable to reference it.</p></li>
- <li><p>Use Eclipse's SVN Repository explorer to checkout all the projects under uimaj/trunk.
- Tell it to create new Java projects for these.</p></li>
- <li><p>
- <code>cd uimaj</code> to switch to the Eclipse workspace project for <code>uimaj</code> (it has the top level
- POM), and run the command:
- <blockquote><code>mvn eclipse:eclipse</code></blockquote>
- </p><p>
- If you haven't run the "install" using maven (because you forgot to follow all the steps under
- "Building from the command line, above"), you should do the command
- <code>mvn install eclipse:eclipse</code>. The "install" argument builds UIMA using maven,
- before the eclipse:eclipse goal is run. This
- is needed for the Eclipse Plugins that are part of UIMA - these projects have their
- "MANIFEST.MF" file built by maven from the information in the maven POMs. This step
- may take a few minutes because the "install" lifecycle includes running the unit tests.
- </p></li>
- <li><p>Return to Eclipse, and if needed, select all the projects and push F5 to "refresh" them (because the
- previous command changed the .project and .classpath files). You can set your workspace to automatically
- refresh - in which case skip this step.</p></li>
- <li><p>The projects should now compile without errors, and have build paths which reference copies of things in
- your local maven repository.</p></li>
- <li><p>You can run the unit tests in Eclipse by right-clicking on a folder (for example
- <code>uimaj-core/src/test/java</code>) and selecting Run As <code>-></code> JUnit Test. This will run all tests
- under that folder.</p></li>
- </ol>
- </p>
- -->
-</subsection>
-
-<subsection name="What to do if the tests fail" id="test.failure">
-<p>
-(Note: this kludgy procedure needs improvement)
-</p>
-<p>
-If you get a failure messsage, the details of the failures are logged in a file
-for each project which has a failue, in the folder target/surefire-reports.
-In Eclipse, you can use the Search facility to search Files in the workspace of type "*.txt"
-for the string "<<< FAILURE!" to locate all the failure messages.
-</p>
-<p>
-If not using Eclipse, you can use <code>grep</code> to accomplish the same thing.
-</p>
-
-<p>You can bypass the tests by doing mvn -Dmaven.test.skip install. But please do this only
- after you've run without it and have verified the tests results.</p>
-</subsection>
+</subsection>
<subsection name="How to build the full Apache UIMA distribution" id="build.distribution">
@@ -366,57 +290,17 @@ mvn install
</pre></longquote>
</p>
+
<p>Sandbox projects are build for distribution individually, by cd-ing to the individual
sandbox project and running "mvn install". Note that this may not work on projects that
are not advanced to the point where they are released - not all projects in the Sandbox are
in a state where they are buildable.
-<!--longquote><pre>
-cd annotator-package
-mvn install
-</pre></longquote-->
</p>
</subsection>
-<subsection name="Building uima-docbooks" id="building.docbooks">
- <p>Docbook processing is done normally as a part of regular maven building of projects
- which have Docbooks.
- The base uimaj projects have 4 docbooks, and there is an aggregate project which builds
- all 4 of these: aggregate-uimaj-docbooks.
- Docbooks are built by the normal maven lifecycle, in the prepare-package phase.</p>
-</subsection>
-
- <subsection name="Creating A4-size PDF documentation" id="building.docbooks.a4">
- <p>The PDF docbook generation defaults to a paper type of USletter. You may override this
- by specifying the maven property "pdfPaperType". You may specify this on the command line
- as follows:
- <code>mvn -DpdfPaperType=A4 package</code>
- </p>
- <p>The allowed values for paper type in Docbook can be seen on this page:
- <a class="external" target="_blank" rel="nofollow"
- href="http://docbook.sourceforge.net/release/xsl/current/doc/fo/page.width.portrait.html">
- http://docbook.sourceforge.net/release/xsl/current/doc/fo/page.width.portrait.html</a>.
- </p>
-
- </subsection>
- <!-- This next section needs rewriting to work with the new docbook system
- <subsection name="Creating A4-size PDF documentation" id="building.docbooks.a4">
- <p>If you don't live in the US, you may wish to create your PDF documentation in a different
- format, e.g., A4. To do this, edit the file
- <code>uima-docbook-tool/properties/default.docbook.properties</code>. It contains a line
- </p>
- <p>
- <code>paper.type = Letter</code>
- </p>
- <p>Change this setting to <code>A4</code> and rebuild the documentation. Note: if you've previously
- built the documentation, you need to run <code>ant clean</code> first, as the build doesn't pick
- up on this change automatically.
- </p>
-
- </subsection>
- -->
-
</section>
+ -->
<!--
<section name="Using Subversion on Windows with cygwin">