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/05/12 16:46:36 UTC
svn commit: r943523 [2/2] - in /uima/site/trunk/uima-website: docs/
docs/board-reports/ xdocs/
Modified: uima/site/trunk/uima-website/xdocs/svn.xml
URL: http://svn.apache.org/viewvc/uima/site/trunk/uima-website/xdocs/svn.xml?rev=943523&r1=943522&r2=943523&view=diff
==============================================================================
--- uima/site/trunk/uima-website/xdocs/svn.xml (original)
+++ uima/site/trunk/uima-website/xdocs/svn.xml Wed May 12 14:46:36 2010
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
@@ -70,12 +70,10 @@ under the License.
<section name="Source Code Repository" id="source.code.repository">
<p>Apache UIMA uses
-<a class="external" rel="nofollow" href="http://subversion.tigris.org">
+<a class="external" rel="nofollow" target="_blank" href="http://subversion.tigris.org">
Subversion</a> to manage its source code.
If you're new to Subversion, you can check out the
-<a href="http://svnbook.red-bean.com/">online book</a> about Subversion.
-Note that we are currently using Subversion 1.1.x (there are separate
-versions of the book covering 1.0 and 1.1).
+<a href="http://svnbook.red-bean.com/" target="_blank">online book</a> about Subversion.
</p>
<p>
@@ -84,7 +82,8 @@ versions of the book covering 1.0 and 1.
<li>http://svn.apache.org/repos/asf/uima/uimaj - the Java code for base UIMA</li>
<li>http://svn.apache.org/repos/asf/uima/uima-as - the Asynchronous Scaleout add-on for base UIMA</li>
<li>http://svn.apache.org/repos/asf/uima/sandbox - a collection of add-ons for UIMA including annotators</li>
- <li>http://svn.apache.org/repos/asf/uima/uimacpp - the C++ framework supporting Annotators written in C++</li>
+ <li>http://svn.apache.org/repos/asf/uima/uimacpp - the C++ framework supporting Annotators written in C++</li>
+ <li>http://svn.apache.org/repos/asf/uima/build - Build information and configurations used in building from sources</li>
</ol>
<p>
Each of these have subdirectories: trunk - for the latest, tags - for preserved copies of releases,
@@ -170,24 +169,47 @@ via HTTPS, in order to be able to check
<subsection name="Checking Out Code using Eclipse" id="checkout.using.eclipse">
-<p>To access the SVN repository from Eclipse, you will need to install the Subclipse plugin from the update site
-<a class="external" rel="nofollow" href="http://subclipse.tigris.org/update_1.0.x">
+<p>To access the SVN repository from Eclipse, please use Maven's m2eclipse plugin
+ from <a class="external" rel="nofollow" target="_blank" href="http://m2eclipse.sonatype.org/sites/m2e">
+ http://m2eclipse.sonatype.org/sites/m2e</a>, and
+ the Subclispe plugin from
+<a class="external" rel="nofollow" target="_blank" href="http://subclipse.tigris.org/update_1.0.x">
http://subclipse.tigris.org/update_1.0.x</a>.
+</p>
+
+<p class="note">Note that m2eclipse comes with a bundled version of maven 3 included. If that version is < 3.0.0-beta-1,
+ please obtain the latest maven 3 build, install it, and then use the preferences for Eclipse Maven to tell
+ it to use the later maven 3 build for running builds.</p>
+
+<p>The individual projects can be checked out without worrying about relative path
+ dependencies, except for a few projects that refer to other projects using relative addresses.
+ Currently, the projects which do that are
+ <ul>
+ <li>the aggregator projects - those special maven projects
+ that only serve to aggregate build operations for a set of other projects, and</li>
+ <li>the "distribution" projects - those that build entire distributions.</li>
+ </ul></p>
+
+<p>The recommended way to check out many projects at once is to use the command line (non-Eclipse) svn checkout
+ command. Use this to check out entire sets of projects under one of the trunks, for instance.
+ Once they are checked out, you can import them into an Eclipse workspace using the
+ File -> Import -> Maven -> Existing Maven Projects.
+</p>
-You can then check out code as follows:
+<p>You can also check out individual projects using
<ol>
<li>Bring up the "SVN Repositories" View (from Window -> Show View -> Other)</li>
<li>Right click in the SVN Repositories View and select New -> Repository Location.</li>
<li>Enter the URL <code>http://svn.apache.org/repos/asf/uima/uimaj/trunk</code> (or <code>https://</code>...)</li>
- <li>Shift-click to select all of the projects, right click and choose "Checkout..."</li>
+ <li>Shift-click to multi-select the projects you want, right click and choose "Checkout as Maven Projects"</li>
<li>Select "Check out into the workspace as projects" and click "Finish"</li>
-</ol>
-
-This will check out all of the code, but as "plain" (that is, not Java) projects.
-To convert the projects to Java projects, you need to do <code>mvn install eclipse:eclipse</code>
-in the uimaj project directory, the uimaj-as project directory, and the SandboxDistr project directory,
-for the base UIMA, UIMA-AS, and the Sandbox Distribution, depending on which ones you checked out.
-See below for more details on these steps.
+</ol>
+</p>
+
+<p class="note">
+ If you check out projects individually, m2eclipse may put them into individual subfolders, causing the
+ distribution and aggregation projects to no longer have the right relative directory specifications.
+ If this happens, the best thing to do is to re-checkout the entire set of related items in one go.
</p>
</subsection>
@@ -268,53 +290,45 @@ http://jira.atlassian.com/browse/SVN-37<
<section name="Building UIMA from Source" id="building.with.maven">
<p>
-Apache UIMA uses Maven 2 to do builds. Release 2.2.x of Maven, or later, is required.
-Download Maven from <a class="external" rel="nofollow" href="http://maven.apache.org">
+Apache UIMA uses Maven 2 or 3 to do builds. Release 2.2.x of Maven, or later, is required.
+Download Maven from <a class="external" rel="nofollow" target="_blank" href="http://maven.apache.org">
http://maven.apache.org</a> and add <maven-home>/bin to your path.
</p>
<p>
- The source can be obtain in two ways:
+ The source can be obtained in two ways:
<ol><li>You can checkout the source from SVN, from trunk, or a particular tagged release, or</li>
<li>you can use the source version of the release artifact you download from the download
page.</li></ol>
</p>
-<p>
- If you want to build the DocBooks from the Docbook sources,
- you need to set up your DocBook tooling by obtaining the needed parts, either from the UIMA SVN
- or from other places on the web (see below). Note that the PDF files only build correctly on a
- Windows platform (due to font issues).
-</p>
<subsection name="Building from the command line" id="building.command.line">
<p>
- To build base UIMA from the command line,
+ These instructions apply to the release 2.3.1 and onwards version. To build base UIMA from the command line,
<longquote><pre>
-$> cd uimaj
+$> cd aggregate-uimaj
$> mvn install
</pre></longquote>
</p>
-<p>Builds for uima-as and the sandbox projects work similarly, however the build process requires that
- base UIMA be in the same containing directory. If you check out these other projects from SVN,
- you will need to copy the projects from these checkouts into the same base directory as
- base UIMA, so all the projects are siblings within that directory. The same is true for building
- from the source distribution.
+<p>Builds for uima-as and the sandbox projects work similarly.
</p>
<p>Once the directory is set up, do:
<longquote><pre>
-$> cd uimaj-as
+$> cd aggregate-uima-as
$> mvn install
or
-$> cd Sandbox
+$> cd aggregate-addons
$> mvn install
</pre></longquote>
</p>
<p>
-This should build all of the jars and run the unit tests. Each jar will be located under the <code>target</code> subdirectory of its project, for example <code>uimaj-core/target/uima-core.jar</code>.
+This should build all of the jars, any docbooks, and run the unit tests.
+The output artifacts (Jars, html and pdf documents, etc.) are placed in each project's "target" directory, and
+also are put into your local Maven repository.
</p>
<p>If you want to build just one of the "projects", and not the whole thing, cd to the project you want to build, and run
@@ -323,7 +337,14 @@ mvn install there.</p>
</subsection>
<subsection name="Building from Eclipse" id="building.eclipse">
- <p>
+ <p>With m2eclipse plugin, you can right-click any maven project, and select Run -> maven commands to do maven runs. Furthermore, you can
+ save run configurations you build using Run -> Run As ... -> Maven build ...; 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 Run As -> JUnit Test. 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>
@@ -360,7 +381,8 @@ mvn -Declipse.workspace=<eclipse work
<code>uimaj-core/src/test/java</code>) and selecting Run As -> JUnit Test. This will run all tests
under that folder.</p></li>
</ol>
- </p>
+ </p>
+ -->
</subsection>
<subsection name="What to do if the tests fail" id="test.failure">
@@ -388,7 +410,7 @@ If not using Eclipse, you can use <code>
details on how to do this.</p>
<p>
-To build a distribution, first do a build as described in "Building from the command line".
+ To build a distribution, first do a build as described in "Building from the command line".
Then (assuming you set up the Eclipse path using one of the first 2 methods, execute the following:
<longquote><pre>
cd ../uimaj-distr
@@ -396,8 +418,7 @@ mvn install
</pre></longquote>
</p>
<p>
-This will build the javadocs and the manual (using docbooks, as described below), will create the
- Eclipse update site for the Eclipse plugins, and will create
+This will build the javadocs, and will create
.zip and .tar.gz archives of the full UIMA distribution in the <code>uimaj-distr/target</code>
directory.
@@ -411,46 +432,27 @@ mvn install
</pre></longquote>
</p>
-<p>Similarly, for building the sandbox distribution, first be sure you've built
- the projects themselves (see above) and then do:
-<longquote><pre>
+<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>
-
-<p>
- This maven command will create the assemblies in the <code>target</code> directory,
- and will also run the Release Audit Tool (RAT) on the result.
- <ul><li>To skip running RAT, use the command <code>mvn package</code>.</li></ul>
+</pre></longquote-->
</p>
</subsection>
-<subsection name="Building uima-docbooks" id="building.docbooks">
- <p>
- The UIMA Source distribution includes the uima-docbook-tool project, which is the tooling needed
- to build the Docbooks; the actual Docbook sources are in the uima-docbooks project, in the src
- directory. The DocBook tooling requires several components that are not included in the source
- distribution, but instead are automatically downloaded from the internet
- the first time you run the tools; you will be asked to accept the licenses for these components.
- Please read the README.FIRST and README files in the uima-docbook directory
- for important information about setting up the tooling. In particular, in order
- to get the images to be rendered in the PDF output, you must obtain the
- "Java Advanced Imaging" library from Sun.
- </p>
-
- <p>Note that the uima-docbooks project is not built using Maven; it is built by an ant script. If you
-want to build the documentation without building the entire UIMA distribution,
-cd to the uima-docbooks directory, and run <code>ant</code>. This will build all 4 books into the
-uima-docbooks/target directory.</p>
-
- <p>Note that each book is actually built twice - the first build only runs the transforms to get the
- links established and setup of cross reference database table. The second outputs the html and pdf files,
- using the cross reference database table just created.</p>
-
+<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>
+ <!-- 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
@@ -465,6 +467,7 @@ uima-docbooks/target directory.</p>
</p>
</subsection>
+ -->
</section>