Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Introduction

There are two ways to use Maven and Eclipse :

1. Use Eclipse as the editor, and Maven command line for commands, or

2. Using an Eclipse plugin for Maven (see Eclipse Integration )

Use the first one if you're much more comfortable with using the command line for your Maven tasks, but would like to take advantage of Eclipse' features ( code complete, refactoring, etc ). Use the second one if you want Eclipse to handle all these things - creation to editing to execution.

For this page, we will discuss the Eclipse plugin for Maven 

Setting up

 To do so, you must install an Eclipse plugin for maven, see Eclipse Integration.

Debugging your Maven Project in Eclipse

Note that there are two debug modes in maven: the Generic and the Surefire. If you want to debug maven itself, one of maven's plugins, or a maven project, use the Generic Approach. If you want to debug a test in your project launched by surefire, use the Surefire Approach.

Most likely, you're debugging your test so try the Surefire Approach. The Generic Approach is more for maven & maven plugin developers.

Setting up Eclipse

Create a Java Project for the Maven Debug session

Create a new Java Project and call it "Maven Debug". This Project will never have any source code in it, it is just a shell for attaching the debugger.

Create Remote Java Application Debug Configurations

Create two debug configurations, one for Generic debugging called "Maven" and one for Surefire debugging called "Maven Surefire"

Run > Debug... and then right click on Remote Java Application and chose New Launch Configuration.

On the Connect tab click the Browse... button and select the "Maven Debug" project. Make sure that the Connection Properties > Port is 8000. (This matches the address value set on the MAVEN_OPTS command line in the mvn-debug.bat file from above)

On the Source tab click Add... and select all projects that have any Maven source that you want to debug.

Now do the same thing to create a second Remote Java Application called "Maven Surefire" with a port of 5005.

Surefire Debugging

Select break points in the code you're are going to run.

From your command line, append the following to your maven command.

Code Block
-Dmaven.surefire.debug


For example, to debug the tests run by the Maven lifecycle install, do mvn install -Dmaven.surefire.debug

Wait for Maven to pause its execution and display the message,

Code Block
Listening for transport dt_socket at address: 5005


Attach the debugger to the running maven by selecting the "Maven Surefire" debug configuration created above.

Generic Debugging

Select break points in the code you're are going to run.

Run Maven in debug mode, e.g mvn-debug install

Attach the debugger to the running maven by selecting the "Maven" debug configuration created above.

Eclipse will now stop Maven at the breakpoints you have enabled.

Setting up Maven 2.0.8+

Note: If you are using Maven 2.0.8 or newer, simply run the "mvnDebug" command in place of "mvn" and skip down to setting up Eclipse.

Setting up Maven <2.0.8

Open %M2_HOME%/bin/mvn.bat

At line 30, you'll find this,

Code Block
@REM set MAVEN_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000



Uncommenting the line by deleting @REM

Also add

No Format
set MAVEN_OPTS=

in the :end section, otherwise the debug will be turned on even when you run the normal mvn.bat 

Save that file as mvn-debug.bat (or any convenient name you may want). You now have two Maven batch files, one for normal use, and one for debugging.

Now when you want to debug maven, run mvn-debug instead of mvn (i.e. instead of mvn install, use mvn-debug install)

Trouble Shooting Debugging

Source not found

I "stepped" into a code block and instead of the source I get "Source not found" with an "Edit Source Lookup Path..." button

This occurs because you do not have a project that contains the source for this class. You will need to checkout the source from the Maven subversion repository and then update the source path of the "Maven Debug" project to include this new project.

First you need to locate which project in the repository the class file belongs to.
Chances are this class exists on your classpath for a project. Select from the menu "Navigate > Open Type..." and enter the name of the class that is missing. In the matching types list select the correct class and click OK.

Ensure "Link with Editor" is enabled in your "Package Explorer". With the missing file selected the Package Explorer should have opened the class from a jar file from the classpath of a project. The name of the jar file should help in locating the project in the Maven subversion repository. The SCM location is also contained in the pom.xml file in the jar, this file is located at META-INF/groupdId/artifactId/pom.xml. E.g for the missing file "MavenArchiver.class" this file is contained in "maven-archiver-2.2.jar" and the pom.xml file in "META-INF.maven.org.apache.maven.maven-archiver" lists the SCM connection as "scm:svn:https://svn.apache.org/repos/asf/maven/shared/tags/maven-archiver-2.2".

Checking out the maven project you need and then run mvn eclipse:eclipse.

From the editor with the missing source, click on "Edit Source Lookup Path..." > "Add..." > "Java Project" > "OK" and select the newly checked out maven project.

The source does not match the debug stack trace

It is more than likely that you have a different version on your source path than the one in use by Maven.

The only way to fix this problem is to have matching versions of source to java class files.
This may require checking out the correctly tagged version of the plugin.

However there is no way to determine which version Maven is using as this is handled by the Plexus classworld's class loader.

Debugging Maven Core with Eclipse

See Re: debugging maven with eclipse written by John J. Franey for some setup guidance. Those instructions should be merged into here at some stage.

FAQ

 Question:

    1. Why can't I just use Generic Debugging even for my tests?

 Answer:

    1. Because maven-surefire-plugin forks a new JVM by default, thus, the your MAVEN_OPTS are not passed. There are three fork modes of maven-surefire-plugin: Once (default), Never, and Always. For Once mode, surefire will run another JVM and will do all its testing there. For Never, it will use the same JVM instance as that of maven (this is normally not use so that you can isolate your tests). But if you really want to isolate your tests, run in Always mode. This will run a new JVM instance for every test sets it runs.

 Question:

    2. Will using argLine parameter of maven-surefire-plugin work instead of the -Dmaven.surefire.debug ? 

 Answer:

    2. Yes. maven.surefire.debug acts like a shorthand version of argeLine=<debugging configuration>. So in most cases, using maven.surefire.debug be enough.