0.10/pushpull/src/site/xdoc/development/maven.xml - oodt - 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.txt 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

      http://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>Using Maven</title>
     <author email="woollard@jpl.nasa.gov">David Woollard</author>
     <author email="sean.hardman@jpl.nasa.gov">Sean Hardman</author>
   </properties>

   <body>
     <section name="Using Maven">
       <p>OODT uses <a href="http://maven.apache.org/">Maven</a> for
       managing our build environment. Maven is an open source product from the
       <a href="http://www.apache.org/">Apache Software Foundation</a> that improves
       on <a href="http://ant.apache.org/">Ant</a> in the area of build management,
       which it turn was an improvement on Make. This document describes the use of
       Maven for Apache OODT build management.</p>
     </section>

     <section name="Setup">
       <p>Maven can be downloaded from the
       <a href="http://maven.apache.org/download.html">Maven Download</a>
       page. OODT is using version 2.0 and above. Maven was developed in Java so it
       will run on the popular platforms (e.g., Windows, Mac OSX, etc.). Beyond
       making sure the <i>mvn</i> executable is in your path, there is very little
       setup required.</p>

       <p>Maven is based on the concept of a Project Object Model (POM) which is
       contained in the <i>pom.xml</i> file found at the root of each project.
       The POM allows Maven to manage a project's build, reporting and documentation.
       For OODT, much of the default information for managing the projects is
       contained in a parent POM, which is located in the <i>oodt-core</i> project. So,
       in order to build any of the other projects (e.g., cas-curator, cas-filemgr,
       etc.) the parent POM must be downloaded from the OODT Maven repository. The
       local <i>pom.xml</i> files for each of the projects have been configured to
       retrieve the parent POM automatically.</p>

       <p>Once Maven has been setup, the first step to building a project with Maven
       is to checkout a project's source code into the developer's work area. See the
       <a href="../development/subversion.html">Using Subversion</a> document for how to
       check out projects from the CM repository.</p>
     </section>

     <section name="Project Structure">
       <p>In order for default Maven functions to operate properly, there is a
       suggested project directory structure. The structure is as follows:</p>

       <source>
 /
   src/             Source Code (everything)
     main/            Program Source
       assembly/        Package Descriptor
       java/            Java Source
       resources/       Scripts, Config File, etc.
         ...
     test/            Test Source
       java/
       resources/
         ...
     site/            Site Documentation
       apt/             Docs in APT Format
         index.apt
         ...
       xdoc/            Docs in XDOC Format
         index.xml
         ...
       resources/
         images/
       site.xml         Menu Structure

   target/          Build Results (binaries, docs and packages)
     ...

   LICENSE.txt
   README.txt
   pom.xml          Project Object Model (POM)
       </source>
     </section>

     <section name="Standard Commands">
     <p>There are few standard commands that developers will use on a daily basis
     and they are related to building and cleaning a project.</p>
     <subsection name="Build a Project">
       <p>Build the project's libraries and executables with the following
       command:</p>
       <source>
 mvn compile
       </source>
       <p>The above command will generate the artifacts in the <i>target/</i>
       directory.</p>
     </subsection>
     <subsection name="Install a Project">
       <p>Install the project's artifacts locally with the following command:</p>
       <source>
 mvn install
       </source>
       <p>Prior to installation, the above command will compile the source code,
       if necessary, and execute the unit tests. The result of the above command
       is to install the generated artifacts (e.g. pom, jar, etc.) in the user's
       local Maven repository ($HOME/.m2/repository/). This is useful when the
       artifact is a dependency for another project but has yet to be deployed
       to the Maven repository.</p>
     </subsection>
     <subsection name="Package a Project">
       <p>Create the project's distribution package with the following command:</p>
       <source>
 mvn package
       </source>
       <p>Prior to package creation, the above command will compile the source
       code, if necessary, and execute the unit tests. The above command will
       create the package(s) in the target/ directory.</p>
     </subsection>
     <subsection name="Build a Project's Web Site">
       <p>Build the project's web site with the following command:</p>
       <source>
 mvn site
       </source>
       <p>The above command will generate the web site in the <i>target/site/</i>
       directory. View the site by pointing your web browser at the
       <i>index.html</i> file within that directory.</p>
     </subsection>
     <subsection name="Clean a Project">
       <p>Clean out the project directory of generated artifacts with the
       following command:</p>
       <source>
 mvn clean
       </source>
       <p>The above command will remove the <i>target/</i> directory and its
       contents.</p>
     </subsection>
     <subsection name="Useful Command Arguments">
       <p>There a couple of useful arguments which can be appended to the
       commands above to limit the scope of the command.</p>
       <p>In order to skip unit test execution, add the following argument:</p>
       <source>
 mvn [command] -Dmaven.test.skip=true
       </source>
       <p>The above command is most useful with the <i>install</i>,
       <i>package</i> and <i>site</i> commands.</p>
       <p>When a project has modules defined in the POM, the command can be
       performed against the top level of the project instead of the modules by
       adding the following argument:</p>
       <source>
 mvn [command] --non-recursive
       </source>
     </subsection>
     </section>
     <section name="Acknowledgments">
       <p>Much of the material in this Maven guide was originally authored
       by Sean Hardman under the sponsorship of NASA Jet Propulsion
       Laboratory's Planetary Data System. </p>
     </section>
     <section name="References">
       <p>Here is a list of Maven resources:</p>
       <ul>
         <li><a href="http://maven.apache.org/guides/index.html">Online
         Documentation Index</a></li>
       </ul>
     </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.txt 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

	http://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>Using Maven</title>
	<author email="woollard@jpl.nasa.gov">David Woollard</author>
	<author email="sean.hardman@jpl.nasa.gov">Sean Hardman</author>
	</properties>

	<body>
	<section name="Using Maven">
	<p>OODT uses <a href="http://maven.apache.org/">Maven</a> for
	managing our build environment. Maven is an open source product from the
	<a href="http://www.apache.org/">Apache Software Foundation</a> that improves
	on <a href="http://ant.apache.org/">Ant</a> in the area of build management,
	which it turn was an improvement on Make. This document describes the use of
	Maven for Apache OODT build management.</p>
	</section>

	<section name="Setup">
	<p>Maven can be downloaded from the
	<a href="http://maven.apache.org/download.html">Maven Download</a>
	page. OODT is using version 2.0 and above. Maven was developed in Java so it
	will run on the popular platforms (e.g., Windows, Mac OSX, etc.). Beyond
	making sure the <i>mvn</i> executable is in your path, there is very little
	setup required.</p>

	<p>Maven is based on the concept of a Project Object Model (POM) which is
	contained in the <i>pom.xml</i> file found at the root of each project.
	The POM allows Maven to manage a project's build, reporting and documentation.
	For OODT, much of the default information for managing the projects is
	contained in a parent POM, which is located in the <i>oodt-core</i> project. So,
	in order to build any of the other projects (e.g., cas-curator, cas-filemgr,
	etc.) the parent POM must be downloaded from the OODT Maven repository. The
	local <i>pom.xml</i> files for each of the projects have been configured to
	retrieve the parent POM automatically.</p>

	<p>Once Maven has been setup, the first step to building a project with Maven
	is to checkout a project's source code into the developer's work area. See the
	<a href="../development/subversion.html">Using Subversion</a> document for how to
	check out projects from the CM repository.</p>
	</section>

	<section name="Project Structure">
	<p>In order for default Maven functions to operate properly, there is a
	suggested project directory structure. The structure is as follows:</p>

	<source>
	/
	src/ Source Code (everything)
	main/ Program Source
	assembly/ Package Descriptor
	java/ Java Source
	resources/ Scripts, Config File, etc.
	...
	test/ Test Source
	java/
	resources/
	...
	site/ Site Documentation
	apt/ Docs in APT Format
	index.apt
	...
	xdoc/ Docs in XDOC Format
	index.xml
	...
	resources/
	images/
	site.xml Menu Structure

	target/ Build Results (binaries, docs and packages)
	...

	LICENSE.txt
	README.txt
	pom.xml Project Object Model (POM)
	</source>
	</section>

	<section name="Standard Commands">
	<p>There are few standard commands that developers will use on a daily basis
	and they are related to building and cleaning a project.</p>
	<subsection name="Build a Project">
	<p>Build the project's libraries and executables with the following
	command:</p>
	<source>
	mvn compile
	</source>
	<p>The above command will generate the artifacts in the <i>target/</i>
	directory.</p>
	</subsection>
	<subsection name="Install a Project">
	<p>Install the project's artifacts locally with the following command:</p>
	<source>
	mvn install
	</source>
	<p>Prior to installation, the above command will compile the source code,
	if necessary, and execute the unit tests. The result of the above command
	is to install the generated artifacts (e.g. pom, jar, etc.) in the user's
	local Maven repository ($HOME/.m2/repository/). This is useful when the
	artifact is a dependency for another project but has yet to be deployed
	to the Maven repository.</p>
	</subsection>
	<subsection name="Package a Project">
	<p>Create the project's distribution package with the following command:</p>
	<source>
	mvn package
	</source>
	<p>Prior to package creation, the above command will compile the source
	code, if necessary, and execute the unit tests. The above command will
	create the package(s) in the target/ directory.</p>
	</subsection>
	<subsection name="Build a Project's Web Site">
	<p>Build the project's web site with the following command:</p>
	<source>
	mvn site
	</source>
	<p>The above command will generate the web site in the <i>target/site/</i>
	directory. View the site by pointing your web browser at the
	<i>index.html</i> file within that directory.</p>
	</subsection>
	<subsection name="Clean a Project">
	<p>Clean out the project directory of generated artifacts with the
	following command:</p>
	<source>
	mvn clean
	</source>
	<p>The above command will remove the <i>target/</i> directory and its
	contents.</p>
	</subsection>
	<subsection name="Useful Command Arguments">
	<p>There a couple of useful arguments which can be appended to the
	commands above to limit the scope of the command.</p>
	<p>In order to skip unit test execution, add the following argument:</p>
	<source>
	mvn [command] -Dmaven.test.skip=true
	</source>
	<p>The above command is most useful with the <i>install</i>,
	<i>package</i> and <i>site</i> commands.</p>
	<p>When a project has modules defined in the POM, the command can be
	performed against the top level of the project instead of the modules by
	adding the following argument:</p>
	<source>
	mvn [command] --non-recursive
	</source>
	</subsection>
	</section>
	<section name="Acknowledgments">
	<p>Much of the material in this Maven guide was originally authored
	by Sean Hardman under the sponsorship of NASA Jet Propulsion
	Laboratory's Planetary Data System. </p>
	</section>
	<section name="References">
	<p>Here is a list of Maven resources:</p>
	<ul>
	<li><a href="http://maven.apache.org/guides/index.html">Online
	Documentation Index</a></li>
	</ul>
	</section>
	</body>
	</document>