[jsword-devel] using maven

[trent.jsword at trentonadams.ca]

First off, a bunch of important pages you may want to look at in regard to maven.

- http://maven.apache.org/
- maven the complete reference book is free at http://www.sonatype.com/books/mvnref-book/reference/public-book.html
- http://maven.apache.org/run-maven/index.html
- http://maven.apache.org/pom.html this is the reference for the various pom elements.
- http://docs.codehaus.org/display/MAVENUSER/MavenPropertiesGuide
- http://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html information on how the build process works

The easiest way to learn the stuff below is to try it, and observe the results.  I show how to use maven from the command line, but any good maven plugin for your IDE, will do the same thing via the GUI.

Basically, maven has what are called "goals" where as ant had "tasks".  The default goals are implicitly bound to the various phases.  See the "Default Lifecycle Bindings" section in the introduction to the lifecycle document I gave above.  A maven plugin can have other goals, such as the maven executor plugin having the "exec" goal, or the dependency plugin having the "tree" goal, which displays your dependency tree (mvn dependency:tree).  Ultimately, goals are what do the work, and they are part of the plugins that anyone can build for maven.

It also has phases, which are phases of building.  Usually you attach goals to a phase, if you desire that a particular plugin goal runs during a particular phase.  For example, if you run the compile phase with "mvn compile" it will call the default binding for that phase, which is "compile:compile" (compile plugin and compile goal).  But, you can also explicitly call a goal, regardless of phase.  For example, I could go "mvn javadoc:javadoc" which means the plugin javadoc and goal javadoc, to generate javadoc.  Or "mvn javadoc:jar" to generate a javadoc jar, using the "jar" goal of the "javadoc" plugin.

A good example of attaching a plugin/goal combination to a phase is in trunk/pom.xml where we "sign" the jars.  Issuing "mvn -Psign install" will package, sign, and install the jars of all submodules into ~/.m2/repository/org/crosswire/*  It does this by using the profile "sign", which is configured to bind the "maven-jarsigner-plugin" and it's "sign" goal, to the "package" phase.

I believe the entire POM XML is accessible as properties at any other point in the pom, but this would need to be confirmed.  For example, I use "${parent.version}" when I want to set the version of the sub modules, because I want them to always be the same as the trunk/pom.xml.  The xpath equivalent would be "/project/parent/version"; in other words the "project" prefix is implied, when referencing them as ${element.subelement}.

Also, any java property is also accessible inside the pom.  For example, you can use "${java.home}" and it will put the absolute path of the system property "java.home" in the location you specified.

You can search to find out if a dependency you need is in the maven repo.  Just navigate through the web pages.  usually in the form of org.apache, com.oracle, etc, or do a google search for it.

http://repo1.maven.org/maven2

Become familiar with the dependency plugin, as it will tell you what is being pulled in for dependencies.  Try a couple of these...
mvn dependency:tree
mvn dependency:copy-dependencies

You can use the tomcat plugin, if you use tomcat for the web pages, or you can use the jetty plugin if you use jetty.  The tomcat plugin allows you to deploy to tomcat remotely, if you have the tomcat manager configured.  You can also run tomcat right from maven by going "mvn tomcat:run" inside "bibledesktop_web" for example.  The jetty plugin lets you run jetty inside maven as well.  Do a google search to find out how to use the two different plugins.