Using Maven

Congratulations! Now that you have installed Maven and/or integrated with your project, you are now ready to start reaping the benefits of Maven. The rest of this document will be a guided tour through the basic operation of Maven's build system. You will learn how to build any of the following Maven-enabled Turbine projects: Torque, Stratum, Fulcrum, and Turbine. The process for each project is the identical thanks to Maven (as are the results).

First, checkout the source for any of the above Turbine projects. If you do not know how to do this, please refer to the CVS Repositories document. For those familiar with the growing family of Jakarta projects, several of the projects include all of the JAR files required to build and distribute the projects in their CVS repositories. Maven eliminates this practice altogether because it provides facilities to automatically download all dependencies from one or more central repositories. Thus, before any Maven goal is executed, Maven will automatically download all of the required dependencies from the remote repositories defined by the ${maven.repo.remote} property.

After Maven has automatically downloaded your dependencies, they are stored in your local repository. Recall, Maven uses this directory to store all JAR files. There are two exceptions: 1) non-distributable JARs will result in a message pointing you to the location where you can download the JAR yourself, and 2) JARs that don't exist in the local or remote repositories will result in an error. In either case, you'll have to download those yourself and manually place them in your local repository. After you have downloaded all of the dependent JARs, generating a JAR for a Maven-enabled Turbine project is easy. Type the following:

You'll notice that all of the code is compiled, and then unit tested, before it is packaged into a JAR file. The unit tests generate reports that are later parsed to create an HTML report that is part of the generated site documentation. The JAR file can also be automatically distributed.

The biggest bang for you buck right now is the generation of your site documentation. Maven will generate documentation that is consistent with the rest of the site. This list of documentation includes: developer lists, mailing lists, dependencies, unit test reports, source code metrics, change logs, JavaDocs, and cross-referenced source code (not too bad considering all you have to do is produce a project descriptor)! It will also create a standard navigation system that is added to all of your xdocs. To generate all of the documentation mentioned above, type the following:

The result of this command is a target/docs directory in the project's base directory that contains an entire web site of documentation.

If you are a maintainer of the project's website, you can use Maven to publish the generated web site to a server. Maven will use the settings defined in the project descriptor to specify various settings (hostname of web server and directory on the server where the site resides) required for deployment. Type the following:

Assuming you have access to the web server, your entire site would have been published. This makes updating the project's web site very easy. It can also be easily automated. Finally, to conclude the example, you might want to clean the project directory because you are so excited about Maven that you want to try everything again! Type the following:

For a full description of all of the Maven goals available type:

That concludes the tour of Maven. All of the Turbine projects currently use Maven to generate their web sites, please have a look and see what Maven can do for you. The Maven-specific content can be found in the navigation section called "Maven Documentation".