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.

Frequently Asked Questions

General

  1. What does Maven mean?
  2. What is Maven 2?

Where Can I Get Help?

  1. Where do I get help on Maven?
  2. How do I find help on a specific goal?
  3. Where can I get help on Jelly?

Contributing

  1. I found a bug. How do I report it?
  2. I have such a cool new idea for a feature. Where do I suggest it?
  3. How do I submit my own fix or new feature?

Using Maven

  1. What's the problem with entities in project.xml?
  2. How do I stop my top level properties being inherited in subprojects? I only want to inherit the project.xml file.
  3. How do I make my build complete even with broken tests?
  4. Where does the output from my JUnit tests go?
  5. How do I disable a report on my site?
  6. How do I use Maven with XDoclet?
  7. Maven takes a long time to load. Is there anyway to speed things up?
  8. Do I need to specify all the dependencies in the POM?
  9. How do I provide multiple source directories in my project.xml?
  10. How can I customise the configuration for an entire installation?
  11. How can I customise Maven's logging?
  12. Why shouldn't I use the dependency classloader override property?
  13. How do I find a plugin's groupId?
  14. How do I add a JAR from a non-Maven project to my local repository?
  15. I share a development machine. How can I share the local repository to save downloading?
  16. I want to store unversioned JARs in the Maven repository, why won't Maven let me?
  17. I've heard that there are lots of great plugins for Maven, where do I find them?
  18. How Do I Install A Third Party Plugin?

Maven's central repository

  1. How do I upload a resource to or update a resource on http://repo1.maven.org/maven/?
  2. Are there any mirrors for the Maven central repository?
  3. Can I search the repositories?

Scripting

  1. How do I get or set plugin properties from Jelly?
  2. How do I spin off a background process in a goal?
  3. How do I get the XSLT tasks to work?
  4. How do I share build code between projects?
  5. How do I share my Maven plugin with others?

Troubleshooting Maven

  1. How can I get Maven to give more verbose output?
  2. Why do the unit tests fail under Java 1.4?
  3. Why does change log ask me to check out the source code?
  4. I have problems generating the changelog report. Why?
  5. maven site fails with bizarre Jelly errors, what can I do?

Ant

  1. What is the equivalent of ant -projecthelp in Maven?
  2. I've heard Maven is much slower than Ant. Is there anything I can do to make it faster?
  3. How can I filter properties into resource files as part of the build?

Building Maven

  1. How do I build Maven?
  2. How do I build Maven from behind a firewall?

General

What does Maven mean?

A maven (yi.=meyvn) is an experienced or knowledgeable person, such as an expert or freak.



What is Maven 2?

Maven 2.0 is a complete rewrite of the 'original' Maven application ('Maven 1'). As such, it is very different from Maven 1, and not backwards-compatible (eg, it cannot execute Maven 1 plugins). However, Maven 2.0 is the latest stable release of the Maven application, and new users are generally encouraged to use it for all new projects.

If you are familiar with Maven 1, you can find some information about moving to Maven 2 here or on the main Maven site.



Where Can I Get Help?

Where do I get help on Maven?

For help getting started, or basic use of Maven, refer to the documentation that can be found from the left navigation of this site.

If these documents, and the other questions in this FAQ don't help you with your problem, the Maven User List is a good source for help. Lots of problems have already been discussed there, so please search the mailing list archive before posting a question or a new idea. Most of the Maven developers are subscribed to the Maven User List, so there is no need to post to the Maven Developers list unless you want to discuss making a change to Maven itself.

Maven developers meet via IRC: irc://irc.codehaus.org#maven, or irc.codehaus.org, channel #maven. But please don't ask for solutions to Maven problems there, as Maven user problems should be discussed at the mailing list for several good reasons (e.g. mail archive, more subscribers) and usually you get a quick answer on the mailing list. But feel free to drop in and say hi.

You should not mail developers directly for Maven related issues, for 2 reasons. The most important is that the project operates in the public, so all discussions should be kept on the list (for the same reasons as given above). Secondly, they are busy and in various timezones, so mailing to the list ensures you get the most prompt response from someone available and able to commit their time at the moment. Direct questions to developers will rarely be answered.



How do I find help on a specific goal?

All Maven goals are provided by plugins. For example, the goals jar and jar:install are provided by the jar plugin. You can find a list of plugins and there documentation here.



Where can I get help on Jelly?

Jelly is a reasonably active project of it's own, used beyond Maven. If you have any questions about it, including how to do certain Jelly things in a Maven build file, you should ask the question on the Jelly mailing lists.

While the Maven User List archive is a good place to search for answers, it is preferred that you only ask Jelly specific questions there if you were unable to find an answer on the Jelly lists.



Contributing

I found a bug. How do I report it?

First, we'd appreciate if you search the Mailing List Archives to see if anyone else has encountered it and found a resolution or a workaround.

If you are not using the current release of Maven, it is also worth trying that, and specifically checking the release notes to see if that bug might have already been addressed.

If you are sure it is a bug, then it should go into JIRA, the issue tracking application for Maven. First, search the Maven project (or related plugin) to see if the bug has already been reported. If not, create a new issue. You must be registered and logged in to do so. This enables you to be contacted if the bug is fixed or more information is required.

The location of Maven's JIRA instance is listed on the Issue Tracking page.

Please be patient. While the issue will usually be reviewed immediately, bugs do not always get fixed as quickly. However, if you are able to submit your own fix, it will usually be applied for the next release. See Submitting Patches for more information.



I have such a cool new idea for a feature. Where do I suggest it?

Great! The process is very similar as for Filing a Bug Report.

Firstly - are you sure its a new idea? Try searching the Mailing List Archives for both the user and developer lists to see if a similar idea has already been discussed.

Likewise, you should also search JIRA to see if someone has proposed it as a feature request already.

If not, there are two ways to proceed. If you have a rough idea but think it needs some discussion with the developers, try posting to the developers mailing list. So that they know initially that you have already thought this through, briefly detail what you did or didn't find when searching the mail archives.

Once you are confident that the idea is solid and fits the current direction of the project, submit it to JIRA as a feature request.

Please be patient. While the issue will usually be reviewed immediately, features are usually not implemented until the start of the next major development cycle. However, if you are able to submit your own implementation, it will usually be applied for the next release. See Submitting Patches for more information.



How do I submit my own fix or new feature?

Bug fixes and features submitted by non-committers of the project take the form of a patch. Submitting your own patch will ensure that the bug or feature gets addressed sooner, and gives the submitter the warm fuzzy feeling from helping out!

Before working on a patch for a bug fix or new feature, it is essential that the steps above are followed to ensure that there isn't already a patch, or that a new feature has been previously decided against because it does not match the direction of the project. You don't want to waste time preparing a patch if it won't be used, so please take the time to consult the current developers list in advance.

When preparing the patch, make sure it is against the latest code in version control by doing a full update and testing it again. The easiest way to prepare the patch is then to run this in the base directory of your source control checkout:

maven scm:create-patch

This is basically equivalent to running svn diff. Attach the resulting patch file to a JIRA issue. Please rename it to the name of the JIRA issue so a developer can save it and still know what it is. Do not mail it directly to a particular developer, or to the developers mailing list as attachments are often stripped or the mails lost.

If you did not create the original JIRA issue, it is important that you select to "watch" the issue so that feedback on the patch can be given.

If you are fixing a bug, make sure you submit a test case that fails without the patch, but succeeds with the patch applied, proving that it works.

If you are submitting a new feature, it is important that you include test cases to verify the feature works, and documentation for users on how it works.

It is important that you don't submit whole replacement files instead of differences or differences where unrelated code is changed - such as changing formatting or spacing. Patches that violate these rules will often not be applied.

Finally, adhere to the coding standards of the project, respecting the settings of the code surrounding that of the change. This includes whitespace, and ensuring that spaces are used instead of tab characters.

If these rules are followed, you will usually find that developers will joyfully and quickly apply the patch, and be appreciative of the efforts put in to help out.



Using Maven

What's the problem with entities in project.xml?

The use of external entities is discouraged in Maven 1.1.

There are several reasons for this, but the main reason is that the content of project.xml needs to be completely self-contained and and able to be reproduced from a history at any point in time.

For this reason, using Jelly expressions other than ${pom.*} references is also not recommended and likely to be unsupported in future.

The most common use of this technique is to manage dependencies across multiple projects. You should strongly consider using inheritence for this purpose.

Note: special character entities will always be supported and should not have any current issues.



How do I stop my top level properties being inherited in subprojects? I only want to inherit the project.xml file.

This is a result of using the same project file at the top level of your multiple project structure as the master build (ie, where you run your multiproject goals from) and the root of your project inheritence tree.

We recommend that you separate these concerns by having both a master build project and a parent project for extension (see the maven-plugins CVS tree for an example). Ther master build should remain in the top level directory, but the shared project file should be in a subdirectory such as common-build.



How do I make my build complete even with broken tests?

See the Test Plugin Reference. Most notably, maven.test.skip and maven.test.failure.ignore. Heed the warnings!



Where does the output from my JUnit tests go?

If you are running test:test, the exceptions will usually be output to ./target/test-reports/some.package.SomeClassTest.txt. If you want to see the errors in the output, set the property maven.junit.usefile to false.



How do I disable a report on my site?

The preferred way is to specify your own <reports/> section in the POM. Reports are not inherited from parent projects, so only those included will be used. The default reports are:

<reports>
  <report>maven-jdepend-plugin</report>
  <report>maven-checkstyle-plugin</report>
  <report>maven-changes-plugin</report>
  <report>maven-changelog-plugin</report>
  <report>maven-developer-activity-plugin</report>
  <report>maven-file-activity-plugin</report>
  <report>maven-license-plugin</report>
  <report>maven-javadoc-plugin</report>
  <report>maven-jxr-plugin</report>
  <report>maven-junit-report-plugin</report>
  <report>maven-linkcheck-plugin</report>
  <report>maven-tasklist-plugin</report>
</reports>

If there is one specific report you want to disable, you can do so with a post-goal. For example, to disable linkcheck whenever the maven.linkcheck.disable property is set, add this to your maven.xml file:

<!-- Conditionally disable linkcheck based on a property. -->
<postGoal name="xdoc:register-reports">
  <j:if test="${maven.linkcheck.disable}">
    <attainGoal name="maven-linkcheck-plugin:deregister"/>
    <echo>linkcheck is disabled.</echo>
  </j:if>
</postGoal>


How do I use Maven with XDoclet?

The XDoclet plugin is provided by the XDoclet developers. All questions about it should be directed to the XDoclet mailing lists.



Maven takes a long time to load. Is there anyway to speed things up?

You can use the Console Plugin to get an interactive shell that will let load Maven once and run as many goals as you want. On average machines it takes something like ten seconds to compile and run unit tests, so that you can build often and test your code often.



Do I need to specify all the dependencies in the POM?

The short answer is YES. Maven 2 will have a transitive dependency discovery mechanism that will avoid this.



How do I provide multiple source directories in my project.xml?

You can't. However, if you really need it, you can use a snippet in maven.xml:

<preGoal name="java:compile">
   <ant:path
       id="my.other.src.dir"
       location="${basedir}/debug/src"/>
   <maven:addPath
       id="maven.compile.src.set"
       refid="my.other.src.dir"/>
</preGoal>

Please think about the reason you need this, and carefully consider whether it is necessary. Usually this is used for writing plugins that handle source generation.



How can I customise the configuration for an entire installation?

Currently you can only configure settings at a project and per-user level. There are no site-wise configuration settings available.



How can I customise Maven's logging?

Maven uses Log4J to log all of its output.

If you would like to write certain information to a file and piping is not an option or you want greater control over what is controlled, you can override the log4j configuration. Refer to the log4j documentation for how to override this using system properties.



Why shouldn't I use the dependency classloader override property?

Because in most cases it isn't needed. root.maven is equivalent to the project classloader, so is never needed. While root is the Ant classloader and has some valid uses, you should not load tasks into it unless absolutely necessary as it will then force itself on the other plugins executed afterwards. In particular any jakarta-commons libraries should not be in the root classloader as these can clash with Jelly.

The correct way to use ant tasks in maven.xml or a plugin is something like:

<ant:taskdef name="checkstyle"
  classname="com.puppycrawl.tools.checkstyle.CheckStyleTask">
  <ant:classpath>
    <ant:pathelement location="${plugin.getDependencyPath('checkstyle:checkstyle')}"/>
    <ant:path refid="maven.dependency.classpath"/>
  <ant:classpath>
<ant:taskdef>


How do I find a plugin's groupId?
  1. Check the plugin's web site page, as should explain how to install it. This information would include the group and artifact ids.
  2. Check for a Downloads link. If one exists, view that page and click the Release Notes for the latest release. The installation information is in the release notes.
  3. If all else fails, look for it in maven repos. A repo search facility exists - refer to the search repositories question.


How do I add a JAR from a non-Maven project to my local repository?

If it is a JAR that cannot be uploaded to Maven's central repository because of a license, or it is private, you must manually copy it to your local repository. After picking a sensible group ID, and making sure the filename is in the format artifactId-version.jar, copy it to ${maven.repo.local}/groupId/jars/artifactId-version.jar.



I share a development machine. How can I share the local repository to save downloading?

It is recommended that you do not share your local repository. The reason for this is that as you build your projects, part of the process is usually to install your changes there for sharing with other projects you are working on that depend on it.

If you share this with multiple developers, you will have to communicate with them about when you will be developing a certain project to ensure your changes don't clash, and ensure each person is always completely up to date.

Usually, it is better to work with a shared remote repository that you run yourself. This means that dependencies are only downloaded once from the internet, and then downloaded to the local cache for each developer as they need it. Company artifacts can also be published there.

See Working with Repositories for more information.

If after this you really want to share a local repository, you can set the maven.repo.local property. This is a directory (not a URL). The directory pointed to must be readable by all of the users and may need to be writable if the users will be allowed to download dependencies or publish their changes. The file system mask must also be set correctly so that changes retain the correct permissions.

Please note that this solution will not be supported by the Maven Users Mailing List, however.



I want to store unversioned JARs in the Maven repository, why won't Maven let me?

There was a workaround to allow this in Maven 1.x, but it will be removed in future. The version is required for Maven's dependency management to work effectively, and besides, it's a good practice.

The local repository is Maven's private cache area, so it is entitled to name the JARs as it sees fit to operate correctly. When you put the resulting JARs into your webapps, etc, you should have the flexibilityo to name them as you wish (though we recommend the default).

You can use a version of UNVERSIONED or similar as a last resort, but it is strongly recommended that you use something recognisable.

You can get more information from the following sources:



I've heard that there are lots of great plugins for Maven, where do I find them?

A list of plugins is maintained by the maven team here but developers of third party plugins are encouraged to host the plugin themselves so you may also need to search the web.



How Do I Install A Third Party Plugin?

See Sharing Plugins



Maven's central repository

How do I upload a resource to or update a resource on http://repo1.maven.org/maven/?

Read Uploading to Maven's central repository.



Are there any mirrors for the Maven central repository?

Yes, there are at least the following:

  • http://repo1.maven.org/maven/
  • http://public.planetmirror.com/pub/maven/
  • http://mirrors.dotsrc.org/maven/
  • http://ftp.up.ac.za/pub/linux/maven/
  • http://download.au.kde.org/pub/maven/


Can I search the repositories?

There is a service available at http://www.mvnrepository.com/ that provides a search service, though not affiliated with the Maven project.



Scripting

How do I get or set plugin properties from Jelly?

Plugin properties can be used with the following tags: maven:get and maven:set. (These replace the deprecated versions of ${pom.getPluginContext(...).get/setVariable()} and maven:pluginVar.)

Example:

<maven:get plugin="maven-war-plugin" property="maven.war.src" var="warSourceDir" />
<echo>The WAR source directory is ${warSourceDir}<echo>
...
<maven:set plugin="maven-multiproject-plugin" property="maven.multiproject.includes" value="subprojects/*/project.xml"/>


How do I spin off a background process in a goal?

For example, before starting unit tests you might need to start a DB server. The DB server blocks until it is terminated, so it needs to be started in the background. <ant:parallel> does not seem to work in this case because it blocks the main execution thread, which is exactly what needs to be avoided.

The solution is given in this thread.



How do I get the XSLT tasks to work?

A common symptom is that the Jelly or Ant tag are output instead of being processed. See MAVEN-156.

The solution is to add the JAXP system property via the Jelly script.

${systemScope.setProperty('javax.xml.transform.TransformerFactory','org.apache.xalan.processor.TransformerFactoryImpl')} 
<ant:style in="${basedir}/some.xml" out="${maven.build.dest}/other.xml" style="${basedir}/sheet.xsl" processor="trax"/> 

Also make sure that Xalan is declared as dependencies in your project file, and added to the root classloader so that Ant can find it:

<dependency>
  <groupId>xalan</groupId> 
  <artifactId>xalan</artifactId> 
  <version>2.3.1</version> 
  <url>http://xml.apache.org/xalan/</url> 
  <properties>
    <classloader>root</classloader>
  </properties>
</dependency>


How do I share build code between projects?

Write your own Maven plugin. It's not as difficult as you may think it is, and it will probably save you much time when your code grows in size.

Please read the Developing Plugins documentation for instructions on how to do this.

It can also be helpful to refer to the source code for the existing Maven plugins which you already have installed.



How do I share my Maven plugin with others?
Read Sharing Plugins.

Troubleshooting Maven

How can I get Maven to give more verbose output?

If you received an exception at the end and want a full stack trace for more information, you can run the same maven command again with the -e switch, eg:

maven -e jar:jar

If you would like a full set of debugging information to trace what Maven is doing, you can run the same maven command again with the -X switch, eg:

maven -X jar:jar

Note that -X implies -e, so there is no need to use both.



Why do the unit tests fail under Java 1.4?

It is possible that the XML parser included with Maven is interfering with the XML parser included in Java 1.4. Please set the ${maven.junit.fork} property to yes.

Note: This may not be necessary under Maven 1.1 as it no longer includes an XML parser, using the one provided by the JDK by default.

Why does change log ask me to check out the source code?

When you run the cvs change log report in Maven, you may see an error occasionally, such as:

cvs [log aborted]: there is no version here; do 'cvs checkout' first
 ChangeLog found: 5 entries

This is caused by the cvs log command finding a directory in it's repository that you don't have locally. Note: The directory may not appear on a checkout or update if it is empty in the repository. Please do a clean checkout of the code and retry the report.



I have problems generating the changelog report. Why?

When you run the cvs change log report in Maven, the report hangs or the final output is blank.

This is typically caused by the cvs command not running correctly. The first port of call is to check Maven's output, search the lines containing for "SCM".

SCM Working Directory: D:\Data\workspace\maven
SCM Command Line[0]: cvs
SCM Command Line[1]: -d
SCM Command Line[2]: :pserver:bwalding@cvs.apache.org:/home/cvsroot
SCM Command Line[3]: log
SCM Command Line[4]: -d 2003-01-27

Try running the command that you find in the log file manually. The results typically speak for themselves.



maven site fails with bizarre Jelly errors, what can I do?
When I try to generate my site I get something like this:
BUILD FAILED
null:58:46:
<x:parse> Invalid source argument. Must be a String, Reader,
InputStream or URL. Was type; java.io.File with value:
/home/jvanzyl/js/com.werken/drools/target/jdepend-raw-report.xml
Total time:  12 seconds

This problem has been observed when a version of Jelly used as a dependency is different than the one distributed with Maven. If you align your versions of Jelly you should be able to generate your site.



Ant

What is the equivalent of ant -projecthelp in Maven?

To some extent, maven -u behaves the same way. For more information, please read the Quick Start guide.



I've heard Maven is much slower than Ant. Is there anything I can do to make it faster?

This has become a bit of an urban myth now, as Maven takes very little more than Ant to initialise (with the exception of the very first run when plugins must be unpacked and parsed).

Part of the misconception comes from claims that building the site or building 30 projects takes a lot of CPU and memory. Well, this would happen in Ant too if it were attempted! Some extensions to Ant that build a web site take considerably longer than Maven to do that task. This area is also a focus for future development so that generating these parts of the build are much faster.

When it comes down to your day to day development and edit-build-test cycle, you can speed up Maven's initialisation time by running the console, as shown in this FAQ answer. This console keeps Maven loaded and ready to do your bidding for a specific project, and makes Maven faster than Ant for performing equivalent, subsequent builds!



How can I filter properties into resource files as part of the build?

This can be done using resource filtering. In your POM, add the filtering property to your existing resources definition. Please refer to Resources for more information.



Building Maven

How do I build Maven?

Please see the Building Maven from Source document.



How do I build Maven from behind a firewall?

You typically need to set your HTTP proxy host and port details so that Maven can tunnel through your HTTP Proxy. To do this you typically need to set the maven.proxy.host and maven.proxy.port properties.

See the Properties Reference for more details.