xdocs/building-uima.xml - uima-site - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>

 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   https://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
 <document>

 <properties>
 <title>Building UIMA</title>
 <author email="dev@uima.apache.org">
  Apache UIMA Documentation Team</author>
 </properties>

 <body>

 <section name="Building Apache UIMA&#0153; from sources">

 <p>
   We use <a class="external" rel="nofollow noopener" target="_blank"
     href="https://maven.apache.org/">Maven</a>, release 3.0 or later, for building.

   Most of us use <a class="external" rel="nofollow noopener" target="_blank"
     href="">Eclipse</a> as the IDE for working with Java.  Maven has a plugin for Eclipse,
   <a class="external" rel="nofollow noopener" target="_blank"
     href="https://m2eclipse.sonatype.org/">m2eclipse</a>, that is useful in working with Maven from
     within Eclipse.
 </p>

 <subsection name="One time initial setup">
   <ul>
     <li>
       <a href="one-time-setup.html#svn-setup">SVN: Click here for the one-time SVN setup</a>.
     </li>
     <li>
       <a href="one-time-setup.html#maven-setup">Maven: Click here for the one-time Maven 3.0 setup</a>.
     </li>
     <li>
       <a href="one-time-setup.html#eclipse-setup">Eclipse: Click here for the one-time Eclipse setup</a>.
        This is only needed if you are using Eclipse as your IDE.
     </li>
   </ul>
 </subsection>

 <subsection name="Building UIMA - using the command line" id="building.command.line">
   <ol>
     <li><p><b>SVN Checkout:</b>
       If the project is a module of a multi-module project (e.g., uimaj),
       check out the SVN directory containing all of the modules for the multi-module project.
       </p>
       <p>For example, (Windows - UIMA-SDK):<br/>
         <code>  svn checkout https://svn.apache.org/repos/asf/uima/uimaj/trunk c:\myWorkingDirectoryForUimaj</code>
       </p>
       <p>If you have <a class="external" rel="nofollow noopener" target="_blank"
     href="https://tortoisesvn.tigris.org/">tortoiseSVN</a> windows shell extensions installed,
     you can use the <code>repo-browser</code> right-click menu option to do this.</p>
     </li>
     <li><p>
       <code>cd to c:\myWorkingDirectoryForUimaj\</code>.</p>
     </li>
     <li><p><code>mvn install</code></p>
       <p>This will build the project and install it to your local Maven repository.
       For multi-module projects, it will build all the submodules.</p>
       <p>However, it <b>won't build the ...-source-release.zip</b> of all
       the sources.  To build this along with the rest of the build, include the
       parameter -Papache-release, like so:<br/>
       <code>mvn install -Papache-release</code>
       </p>
     </li>
   </ol>

   <p>
     The build process builds all of the jars, any docbooks, runs the unit tests and other
     validity checks, and may build a multi-module binary assembly (varies according to each project).
     The output artifacts (Jars, html and pdf documents, etc.) are found in
     each module's "target" directory, and
     also are put into your local Maven repository.
     Docbook output is placed in each project's target/site/d directory.
   </p>
   <p>Multi-module builds create the build artifacts (including the binary assembly) in the <code>target</code> folder of their top level project.
   </p>
 </subsection>

 <!--subsection name="Building just one module for a multi-module project" id="building.command.line.one">
   <p>Check out all of the modules, as above (because single modules may have dependencies
          on other artifacts in the checkout).
   </p>
   <ol>
     <li><p>
       <code>cd to the sub directory of the particular module you want to build</code>.
       </p>
     </li><li><p>Issue the command:
       <code>mvn install</code></p>
       <p>This will build just that module and install it to your local Maven repository.</p>
     </li>
   </ol>
 </subsection-->

 <subsection name="Building using Eclipse, with the m2eclipse plugin" id="building-from-eclipse">
   <ol>
     <li>Checkout from SVN exactly as above, into some location.  Then use
       Eclipse menu: <code>File -> Import -> Maven -> Existing Maven projects</code>
       to import the project or projects (for multi-module projects) into an Eclipse workspace
       and set them up for Maven building.</li>
     <li>To run Maven commands on a project from within Eclipse, select the project, right click, and pick <code>Run as</code>
       and then select <code>mvn install</code> (or other choice as you wish).</li>
   </ol>

   <p class="note"><big><b>Help! I'm getting compile errors (class not found) in Eclipse!</b></big>
     If your Maven build generates sources (e.g., you have some XMLBeans defined),
     then after the initial import and project build, you'll need to use the m2eclipse command
     <code>Update Project Configuration</code> found on the <code>Maven</code> context menu
     obtained by right-clicking the project folder.
     This will add the generated classes to Eclipse's classpath.</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>

  </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 noopener"
   href="https://docbook.sourceforge.net/release/xsl/current/doc/fo/page.width.portrait.html">
   https://docbook.sourceforge.net/release/xsl/current/doc/fo/page.width.portrait.html</a>.
   </p>

   </subsection>


 <!--  not supported by 0.12 release of m2eclipse -->
 <!--subsection name="Checking Out Code using Eclipse" id="checkout.using.eclipse">

 <p>To access the SVN repository from Eclipse, use Maven's m2eclipse plugin
   and the Subclipse plugin.
 </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
   <code>File -> Import -> Maven -> Existing Maven Projects</code>.
 </p>

 <p>You can also check out individual projects using
 <ol>
   <li>Bring up the "SVN Repositories" View (from <code>Window -> Show View -> Other</code>)</li>
   <li>Right click in the SVN Repositories View and select <code>New -> Repository Location</code>.</li>
   <li>Enter the URL <code>https://svn.apache.org/repos/asf/uima/uimaj/trunk</code> (or <code>https://</code>...)</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>
 </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-->


 <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 message, the details of the failures are logged in a file
 for each project which has a failure, 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 "&lt;&lt;&lt; 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>

 </section>


 </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<document>

	<properties>
	<title>Building UIMA</title>
	<author email="dev@uima.apache.org">
	Apache UIMA Documentation Team</author>
	</properties>

	<body>

	<section name="Building Apache UIMA from sources">

	<p>
	We use <a class="external" rel="nofollow noopener" target="_blank"
	href="https://maven.apache.org/">Maven</a>, release 3.0 or later, for building.

	Most of us use <a class="external" rel="nofollow noopener" target="_blank"
	href="">Eclipse</a> as the IDE for working with Java. Maven has a plugin for Eclipse,
	<a class="external" rel="nofollow noopener" target="_blank"
	href="https://m2eclipse.sonatype.org/">m2eclipse</a>, that is useful in working with Maven from
	within Eclipse.
	</p>

	<subsection name="One time initial setup">
	<ul>
	<li>
	<a href="one-time-setup.html#svn-setup">SVN: Click here for the one-time SVN setup</a>.
	</li>
	<li>
	<a href="one-time-setup.html#maven-setup">Maven: Click here for the one-time Maven 3.0 setup</a>.
	</li>
	<li>
	<a href="one-time-setup.html#eclipse-setup">Eclipse: Click here for the one-time Eclipse setup</a>.
	This is only needed if you are using Eclipse as your IDE.
	</li>
	</ul>
	</subsection>

	<subsection name="Building UIMA - using the command line" id="building.command.line">
	<ol>
	<li><p><b>SVN Checkout:</b>
	If the project is a module of a multi-module project (e.g., uimaj),
	check out the SVN directory containing all of the modules for the multi-module project.
	</p>
	<p>For example, (Windows - UIMA-SDK):<br/>
	<code> svn checkout https://svn.apache.org/repos/asf/uima/uimaj/trunk c:\myWorkingDirectoryForUimaj</code>
	</p>
	<p>If you have <a class="external" rel="nofollow noopener" target="_blank"
	href="https://tortoisesvn.tigris.org/">tortoiseSVN</a> windows shell extensions installed,
	you can use the <code>repo-browser</code> right-click menu option to do this.</p>
	</li>
	<li><p>
	<code>cd to c:\myWorkingDirectoryForUimaj\</code>.</p>
	</li>
	<li><p><code>mvn install</code></p>
	<p>This will build the project and install it to your local Maven repository.
	For multi-module projects, it will build all the submodules.</p>
	<p>However, it <b>won't build the ...-source-release.zip</b> of all
	the sources. To build this along with the rest of the build, include the
	parameter -Papache-release, like so:<br/>
	<code>mvn install -Papache-release</code>
	</p>
	</li>
	</ol>

	<p>
	The build process builds all of the jars, any docbooks, runs the unit tests and other
	validity checks, and may build a multi-module binary assembly (varies according to each project).
	The output artifacts (Jars, html and pdf documents, etc.) are found in
	each module's "target" directory, and
	also are put into your local Maven repository.
	Docbook output is placed in each project's target/site/d directory.
	</p>
	<p>Multi-module builds create the build artifacts (including the binary assembly) in the <code>target</code> folder of their top level project.
	</p>
	</subsection>

	<!--subsection name="Building just one module for a multi-module project" id="building.command.line.one">
	<p>Check out all of the modules, as above (because single modules may have dependencies
	on other artifacts in the checkout).
	</p>
	<ol>
	<li><p>
	<code>cd to the sub directory of the particular module you want to build</code>.
	</p>
	</li><li><p>Issue the command:
	<code>mvn install</code></p>
	<p>This will build just that module and install it to your local Maven repository.</p>
	</li>
	</ol>
	</subsection-->

	<subsection name="Building using Eclipse, with the m2eclipse plugin" id="building-from-eclipse">
	<ol>
	<li>Checkout from SVN exactly as above, into some location. Then use
	Eclipse menu: <code>File -> Import -> Maven -> Existing Maven projects</code>
	to import the project or projects (for multi-module projects) into an Eclipse workspace
	and set them up for Maven building.</li>
	<li>To run Maven commands on a project from within Eclipse, select the project, right click, and pick <code>Run as</code>
	and then select <code>mvn install</code> (or other choice as you wish).</li>
	</ol>

	<p class="note"><big><b>Help! I'm getting compile errors (class not found) in Eclipse!</b></big>
	If your Maven build generates sources (e.g., you have some XMLBeans defined),
	then after the initial import and project build, you'll need to use the m2eclipse command
	<code>Update Project Configuration</code> found on the <code>Maven</code> context menu
	obtained by right-clicking the project folder.
	This will add the generated classes to Eclipse's classpath.</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>

	</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 noopener"
	href="https://docbook.sourceforge.net/release/xsl/current/doc/fo/page.width.portrait.html">
	https://docbook.sourceforge.net/release/xsl/current/doc/fo/page.width.portrait.html</a>.
	</p>

	</subsection>


	<!-- not supported by 0.12 release of m2eclipse -->
	<!--subsection name="Checking Out Code using Eclipse" id="checkout.using.eclipse">

	<p>To access the SVN repository from Eclipse, use Maven's m2eclipse plugin
	and the Subclipse plugin.
	</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
	<code>File -> Import -> Maven -> Existing Maven Projects</code>.
	</p>

	<p>You can also check out individual projects using
	<ol>
	<li>Bring up the "SVN Repositories" View (from <code>Window -> Show View -> Other</code>)</li>
	<li>Right click in the SVN Repositories View and select <code>New -> Repository Location</code>.</li>
	<li>Enter the URL <code>https://svn.apache.org/repos/asf/uima/uimaj/trunk</code> (or <code>https://</code>...)</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>
	</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-->


	<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 message, the details of the failures are logged in a file
	for each project which has a failure, 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>

	</section>


	</body>
	</document>