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.
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:
||This will contain all types of source files under the following subdirectories.|
||This is intended for the main part of the application - the code that would be part of the final distributable.|
||This is the java code that makes up the application. Below this should be a package structure.|
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
||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.|
||This is the java code that makes up the unit tests for the application. Below this should be a package structure.|
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
adopted in Maven 2, where it defaults to
Now, you are ready to start defining the project layout for Maven.
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
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
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/docsand see what it will look like
Note that you can download some sample code instead of creating the project above.
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
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
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
As was shown previously, the project descriptor is all that is initially needed to generate a site for your project by running:
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="email@example.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:
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.
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:
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.