Being Prepared

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:

1. Expand plugins into a cache directory
2. Download additional dependencies for the plugins and project being built

The Properties Reference explains how to configure Maven to use different locations for the cache and download repository. By default, these reside under $HOME/.maven.

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:

• All Maven projects (including Maven and its plugins) share the repository, so each dependency is only downloaded once.
• This avoids needing to download each dependency manually and place it in the correct place for each build.
• No large binaries need to be stored in CVS where they are downloaded and checked for updates often.
• Maven automatically and uniformly handles proxy servers, multiple remote sources and mirrors.

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.

Common Tasks

Maven provides standard tasks for common operations. For example, to build a JAR from the current project, run:

maven jar

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 target/classes directory.

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:

maven site

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:

maven clean

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.

Help in Ant

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. A 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.

Help for a Maven project without a maven.xml file

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 then 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.

Help for a Maven project with a maven.xml file

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.

Where it usually goes wrong in Maven

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 maven build:end 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 project.xml).

More Help

For a complete reference on how to get help about building a Maven project from the command line, see the Maven Command Line Reference.