| <?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> |