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:

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.