Apache Maven 1.x has reached its end of life, and is no longer supported. For more information, see the announcement. Users are encouraged to migrate to the current version of Apache Maven.

The Ten Minute Test - Creating a Project with Maven 1.x

Often when evaluating a new piece of software, you want to give it the "ten minute test" - download, install and run it, and then do something useful with it within 10 minutes to get a feel for how it works. It can be a lot more useful than reading the manual. This guide will help you do that.

Sure, you won't have converted any massive, highly-customised build you may already be using, but you'll know where to start.

Beforehand, it is worth getting familiar with how to run Maven. Please read the Quick Start for important instructions on how to install Maven, and download dependencies, and learn the basics for running it.

If you are already very familiar with Ant, you may also like to refer to the Migrating from Ant guide.

Step 1: Setting up the directory structure

As you'd expect, the first steps are to set up the required directories. The small project will be an echo program.

mkdir sample-echo
cd sample-echo

From here, you could use the genapp plugin to generate a skeleton project for you. However, here we will start from scratch so that each element can be explained.

While you can set up almost any directory structure and use it with Maven, there is a standard directory structure defined that is recommended. The reasons for this are explained in the definition, but essentially ensure minimal extra configuration by you, and make it easier for users familiar with Maven to navigate your project.

Let's continue by creating the following directory layout:

sample-echo [current directory]
+- src
   +- main
      +- java
         +- samples [package structure]
            +- echo
      +- resources
   +- test
      +- java
         +- samples [package structure]
            +- echo
+- xdocs

The following is an explanation of what each directory's purpose is:

src This will contain all types of source files under the following subdirectories.
src/main This is intended for the main part of the application - the code that would be part of the final distributable.
src/main/java This is the java code that makes up the application. Below this should be a package structure.
src/main/resources These are additional resources for copying into the final distributable. This may have a subdirectory structure that is maintained, including using a package structure. For example, you might have a META-INF/MANIFEST.MF file in here (although Maven does create a default one for you so this isn't usually necessary).
src/test This contains everything needed to unit test your application. You may have additional similar directories later if you add other types of tests such as integration tests using Cactus.
src/test/java This is the java code that makes up the unit tests for the application. Below this should be a package structure.
src/test/resources As for src/main/resources, but only made available to the unit tests. Not used in this example.
xdocs This contains the documentation that will be transformed into HTML and published as a project site. Note: by defaulting the xdocs location to the top level directory, Maven 1.x violates the directory structure conventions adopted in Maven 2, where it defaults to src/site/xdoc. You can make your project layout compatible with Maven 2 by overriding the maven.docs.src property.

Now, you are ready to start defining the project layout for Maven.

Step 2: Create a project descriptor

The most important file to Maven is project.xml. While you can run Maven without it, it will not know anything about your project - so is only useful for project-independant goals such as scm:checkout or genapp.

Different people have different preferences for how they create their project descriptor. Some will copy from an existing project and edit, some will run maven genapp and accept the defaults to get a skeleton project, and some will hand-edit it from scratch. In the near future, tools will be available to graphically edit the project descriptor.

The following is a basic project descriptor:

<project xmlns="http://maven.apache.org/POM/3.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/3.0.0 http://maven.apache.org/maven-v3_0_0.xsd">
  <pomVersion>3</pomVersion>
  <groupId>sample</groupId>
  <artifactId>sample-echo</artifactId>
  <name>Sample</name>
  <currentVersion>1.0-SNAPSHOT</currentVersion>
  <inceptionYear>2005</inceptionYear>
  <dependencies>
    <dependency>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
      <version>1.2.8</version>
    </dependency>
  </dependencies>
  <build>
    <sourceDirectory>src/main/java</sourceDirectory>
    <unitTestSourceDirectory>src/test/java</unitTestSourceDirectory>
    <resources>
      <resource>
        <directory>src/main/resources</directory>
      </resource>
    </resources>
    <unitTest>
      <includes>
        <include>**/*Test.java</include>
      </includes>
    </unitTest>
  </build>
</project>

There are many more elements to be introduced as you develop, especially if you want to make releases or publish a site. A full description of the project descriptor is available. Often, common elements will be shared in a parent descriptor to keep each as small as possible.

The above descriptor is all you need to build a JAR and run any tests associated with it. Try it for yourself: add some Java code to the src/main/java directory (include subdirectories for any package name), and a JUnit test under src/test/java. The following goals will perform some standard behaviours:

  • maven java:compile - this will compile the code and check for errors - nothing more
  • maven test - this will compile the code and tests, then run all of the unit tests
  • maven jar - this will build a JAR from your code, after running the tests as above
  • maven site - even now, you can generate a site in target/docs and see what it will look like

Note that you can download some sample code instead of creating the project above.

Customising the Build

In addition to the project descriptor, a number of properties can be set to customise the way the build performs. For example, say you wanted to change some properties regarding compilation for the project. You can create a project.properties file in the same location as your project.xml file.

maven.compile.source=1.3
maven.compile.target=1.1
maven.compile.debug=true

There are a great number of customisation properties available, each relating to individual plugins and some for Maven itself. For example, the above properties are defined for the Java plugin which provides the java:compile goal.

You can usually find a reference of the properties that will customise a plugin in each respective plugin's documentation. A list of plugins can be found in the Plugins Reference, which is also linked in the navigation of this site.

There are also a number of standard properties defined by Maven itself, which are listed in the properties reference.

Properties are read in a particular order - while usually they will be defined in project.properties to share with all users of your project, sometimes they are specific to your environment (eg, when they include paths on your machine). In this case they should be included in build.properties in either the project directory (if they are specific to the project) or in your home directory (if they are for every project on your machine under your account). For more information about the order properties are loaded, see the properties reference.

Generating the Site

As was shown previously, the project descriptor is all that is initially needed to generate a site for your project by running:

maven site

The next step in this process is to add some custom documentation to the site. This might be some basic usage instructions, linking out the Javadoc and other references, or it might be a complete project site depending on your preference.

To try this, add a file called xdocs/index.xml in your project with the following content:

<document>
  <properties>
    <title>Hello World</title>
    <author email="me@mycompany.com">Me</author>
  </properties>

  <body>
    <section name="Section 1">
      <p>
        Hello world!
      </p>
    </section>
  </body>
</document>

To view your new index page in target/docs/index.html, regenerate the site again:

maven site

Any XHTML will be accepted within the <section /> tags, as well as other special tags. Some HTML, such as tables, are also styled specially. For more information on building a site, see the User's Guide.

Where to next?

Thanks for giving Maven the ten minute test! If you have any feedback (positive and negative), please email the Maven Users List.

This tutorial has hopefully given enough information on how easy it is to start a new project with Maven. Luckily, creating more complex projects is just as easy as Maven encourages you to build up projects consistently, like building blocks.

For more information on beginning with Maven, the book Maven: A Developer's Notebook has a sample chapter online that deals with getting started.

It is recommended that you read the areas of the User's Guide that relate to the particular type of project you are working on next. This includes:

  • Utilising source control
  • Working with multi-module projects
  • Releasing a project and deploying it to a repository

As previously mentioned, you can also find more help on using a particular plugin in each plugin's documentation mini-site, which are listed in the Plugins Reference. There is also a Reference area for more general Maven documentation.