If you find you don't understand the meaning of a term, you should refer to the Glossary for commonly used terminology that is either unique to Maven or has a special meaning.
Maven will run with sensible defaults, so you can get right into it. However, if you are operating under a particularly restrictive environment you might need to prepare to run Maven. When Maven first runs it will:
The Properties Reference explains how to configure Maven to use
different locations for the cache and download repository. By default, these reside under
The first time a project is built or a specific plugin is used, you may need to be online to obtain dependencies. If you have them, JARs can be put into your local repository manually if desired, and you can also run a local mirror of needed dependencies. For more information, refer to Working with Repositories.
This might seem onerous, but remember the following advantages:
Occasionally, some dependencies will not be downloadable because of the distribution license they have. These must be downloaded manually and placed into the local repository. This is explained for the commonly requested Sun reference JARs. See Standard Sun JAR names for more information.
Maven provides standard tasks for common operations. For example, to build a JAR from the current project, run:
You'll notice that all of the code is compiled, the unit tests are run, and finally it is packaged into a JAR file. The unit tests generate reports that can later be parsed to create an HTML report that is part of the generated site documentation. The JAR file can also be automatically distributed if making a release, or shared with other local projects.
The output of this task is in the
target directory, as with all Maven output. For example:
target/classes- compiled source classes and resources
target/test-classes- compiled test classes and resources
target/test-reports- Text and XML representations of the test results
target/project-X.Y.Z.jar- the output JAR, built from the
For more information on the JAR plugin, including references for goals and properties, see the jar plugin documentation.
The individual goals that make up the JAR goal can also be called individually, for example:
maven java:compile maven test
If you are not building a JAR, there are other plugins for building different types of artifacts. Examples of these can be seen from the "Using Maven" section in the left hand navigation.
Another common task when building from the source is to build a local copy of the project site for documentation and reference. This is done with the goal:
Note: building the site can require a large number of dependencies to be downloaded the first time as several different reports are run.
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 the website maintainer, you can also publish this to a
local or remote web server.
As for any plugin, more information on the
site goals can be
seen in the site plugin documentation.
In addition to a goal and property reference, some plugins also have their own set
of FAQs and examples.
To clean up after a build and start fresh, simply run:
While the standard goals suffice for most day to day usage of Maven, there are plenty of other plugins to use. The next section will explain how to get specific help building a project.
For information on incorporating Maven into your own project, start with the Ten Minute Test.
Ok, you have a project you've just downloaded, and you know it builds with Maven. There's no documentation to speak of for the project itself, so where to start?
If you were using Ant, you'd probably run
ant -projecthelp, and if that didn't help,
just run "ant" and hope the default target is what you wanted.
build.properties.sample file may have been provided so you'd copy that and edit it to see
if that helped. Then you'd fix individual problems as they came up.
If everything goes wrong and you can't find the right target or what property it's expecting, you dig into
build.xml and look at what it is attempting.
The process for Maven should be at least as easy, and usually simpler.
If there is no
maven.xml file, then you know the build hasn't been customised so you can rely on
a few things working.
If you know it is a JAR,
maven jar should do what you expect. If you know it is a web application
maven war should produce the expected results, and if there are subprojects,
maven multiproject:artifact is the standard build task. Finally,
maven site (or
maven multiproject:site) should produce some documentation or at least the standard reports.
Though it is much less likely than in Ant, a
build.properties.sample file may have been
provided so you'd copy that and edit it too.
Otherwise, you shouldn't expect to have to define any properties outside what the project has provided and you have already defined to get Maven running, as only the standard Maven plugin properties are being used, and you know how they behave.
If there is a
maven.xml file, then the build has been customised. You can still rely on the
above goals doing what they advertise, but they might not be the recommended way of building that
particular project. This is especially true when projects define their own multi-project structure without
using the multiproject plugin to build.
The first step would be to run
maven -u. Similar to
ant -projecthelp, it
will list all of the goals in
maven.xml and any description listed with the goal by the
author. Standard goals like
jar will be omitted as their behaviour is already known.
You may just run
maven and rely on the default goal being what you wanted.
You may still get some of the ant problems, where the above doesn't help or the properties are required
and not defined. The same process will apply here - you investigate
maven.xml which should be
much shorter as it only contains customisations.
There will always be bad builds under either system, but Maven gives you quite a head start by providing a standard set of build pieces that you can expect to work out of the box.
Having said that, there are still a few areas where a Maven build won't work out of the box. By far the most common occurrence of this is depending on a JAR that is not published to a public place. This might be because of licensing (eg a lot of the standard Sun JARs cannot be redistributed by Maven), or because it is a development build of some library that was being built locally. For more information, see Standard Sun JAR names.
If you are downloading the source to a project, it is always worth running
once on each
project.xml. This won't do anything except download all the dependencies
the project wants. If some can't be found, then you should track them down while still online.
If it has been particularly troublesome and undocumented, you might want to harass
the authors of the project via their users mailing list (which you should also find in
For a complete reference on how to get help about building a Maven project from the command line, see the Maven Command Line Reference.