Developing with Maven

Trying It Out

If you are ready to try using Maven, here are the steps to take to set it up on your system.

• Download the latest release from the Apache Maven site.
• Extract the files onto your system. For example, the directory C:\maven or ~/maven.
• Set the MAVEN_HOME environment variable to point to the directory where you extracted the files.
• Verify that you have an environment variable set for JAVA_HOME.
• Add the MAVEN_HOME/bin directory to your path.

Now, if you enter the following command:

maven -v

You should see the following output:

 __  __

|  \/  |__ _Apache__ ___

| |\/| / _` \ V / -_) ' \  ~ intelligent projects ~

|_|  |_\__,_|\_/\___|_||_|  v. 1.0-beta-10

Not only is Maven working, but you get cool ASCII art as well! To see what options are available when you invoke Maven, type:

maven -h

To see the list of available goals, type:

maven -g

What you see in the output is a long list of plug-ins and the goals they provide:

Available [Plugins] / Goals

```````````````````````````

[ant] : Generate an Ant build file

  generate-build ............. Generate an Ant

                               build file



[antlr] ( NO DEFAULT GOAL )

  generate ................... Generate source 

                               from antlr grammars

  prepare-filesystem ......... Make any necessary

                               directories for antlr

                               processing

Further down in the list, you will see the plug-in [wizard], with the goal ui. You would attain that goal by typing the following command:

maven wizard:ui

When you type this, you'll see output messages indicating Maven is going to its repository and downloading any needed .jars.

To get more familiar with Maven, let's create a sample project. For this example, we'll create a directory called maven-sample, in ~/maven-sample or C:\maven-sample. Then run the following command:

maven -D package=com.oreillynet.mavensample genapp

This will generate a complete simple startup project for you. Make sure you enter the package name as specified above when prompted at the console. If you don't, you will get compile errors.

Now run the command:

maven site:generate

This instructs Maven to generate the site for the project. This is generated based on the POM file (project.xml) that was configured. When you run this command for the first time, you will notice that Maven goes to its own repository and downloads any .jars that are needed.

By running that one goal, Maven has compiled your code, copied over any resources (properties files) from the conf directory into your classes directory, produced Javadoc documentation, and run all of the project comprehension and analysis reports. That's an incredible amount of functionality for one goal!

If you look in the target directory, you'll see the output of the site:generate goal. Open the docs directory under target, and open the index.html in your favorite web browser. You will see the reports Maven generated for the sample application.

Ant Tasks in Maven

To integrate any Ant task into your Maven build process, you need to create a file called maven.xml in the same directory as your project.xml. Add the following XML code to the maven.xml file:

<project default="myGoal">

  <goal name="myGoal">

    <echo>Hello Maven!</echo>

  </goal>

</project>

The <echo> task is a simple Ant task that just displays the text between the tags when the task is run. When constructing your own goals in Maven, you can use any valid Ant task.

Save the file, then run the following command from the directory where your project.xml and maven.xml files reside.

maven

You should see the following output:

myGoal: 

   [echo] Hello Maven!

BUILD SUCCESSFUL

Total time:  1 seconds

Customizing Maven

Now that you have seen the basic sample project working, you can start customizing Maven for your own project's needs. If you open up project.xml in your favorite text editor, you will see the generated and commented file. You can use this as a base for your own projects and edit the file as necessary. What's nice about this approach is that you have a working project right from the beginning, and can then add your source code and other resources to the project.

If you are using the Checkstyle plug-in, you can set what coding style you would like to use in the project.properties file. This plug-in, by default, comes with the standard Sun and Turbine coding styles. If your team's style is different, you can define your own! First, set maven.checkstyle.properties=team-checkstyle.xml.

This tells the plug-in to look for a file called team-checkstyle.xml that contains the settings for your team's style. To create yours from scratch, you can use the excellent Eclipse plug-in, or use one of the standard ones and customize it. Open the MAVEN_HOME/plugins directory and then extract the files from the maven-checkstyle-plugin .jar. Under the expanded .jar's plugin-resources directory, you will see sun_checks.xml and turbine_checks.xml. Pick the one that is the closest match to your team's style and then alter as needed.

To change some of the default colors used when the project site is generated, you can change the following properties in the project.properties file. You specify the colors in the typical HTML style. In this case we have set the section, banner, and source colors.

maven.ui.section.background=#cfcfbb

maven.ui.banner.border.top=#cfcfbb

maven.ui.banner.background=#cfcfbb

maven.ui.source.background=#cfcfbb

If you need to define a dependency that is used in your company but is not available in the Maven repository at ibiblio.org, you can define the dependency like this:

<dependency>

  <id>SomeJar</id>

  <jar>someJar1.2.jar</jar>

</dependency>

You then need to place a someJar1.2.jar file in your repository. This directory location is controlled by the maven.repo.local property in your project.properties file. This defaults to ${maven.home.local}/repository, which in turn resolves to ${user.home}/.maven. If you would like to customize the reports that get generated, then add the following <reports> element to your project.xml:

<reports>

  <report>maven-checkstyle-plugin</report>

  <report>maven-changelog-plugin</report>

  <report>maven-developer-activity-plugin</report>

  <report>maven-file-activity-plugin</report>

  <report>maven-javadoc-plugin</report>

  <report>maven-jdepend-plugin</report>

  <report>maven-junit-report-plugin</report>

  <report>maven-jxr-plugin</report>

  <report>maven-statcvs-plugin</report>

  <report>maven-simian-plugin</report>

</reports>

All but the last two of these reports are generated by the standard configuration. This adds maven-statcvs-plugin, which generates statistical cvs reports, and the maven-simian-plugin that identifies duplicated lines of code in a project. Once you define a <reports> element, you override any of the reports that would get generated by default.

Conclusion

This article has provided a basic introduction to the features of the Apache Maven project. Using Maven should help streamline your team's build process and give you insight into the current status of your code.

Maven's developers, and the community of users, have created an excellent build tool. Thank you!

Rob Herbst is a developer whose interests include Java, Linux, and .NET

Return to ONJava.com.