General
Where Can I Get Help?
Contributing
Using Maven
project.xml
?
project.xml
file.
project.xml
?
Maven's central repository
Scripting
Troubleshooting Maven
Ant
ant -projecthelp
in Maven?
Building Maven
A maven (yi.=meyvn) is an experienced or knowledgeable person, such as an expert or freak.
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.
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.
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.
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.
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.
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.
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.
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.
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
.
See the Test Plugin Reference.
Most notably, maven.test.skip
and maven.test.failure.ignore
.
Heed the warnings!
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
.
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>
The XDoclet plugin is provided by the XDoclet developers. All questions about it should be directed to the XDoclet mailing lists.
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.
The short answer is YES. Maven 2 will have a transitive dependency discovery mechanism that will avoid this.
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.
Currently you can only configure settings at a project and per-user level. There are no site-wise configuration settings available.
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.
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>
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
.
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.
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:
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.
See Sharing Plugins
Read Uploading to Maven's central repository.
Yes, there are at least the following:
There is a service available at http://www.mvnrepository.com/ that provides a search service, though not affiliated with the Maven project.
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"/>
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.
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>
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.
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.
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
.
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.
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.
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 -projecthelp
in Maven?
To some extent, maven -u
behaves the same way. For more information, please read the
Quick Start guide.
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!
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.
Please see the Building Maven from Source document.
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.