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
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"
Debug... and then right click on
Remote Java Application and chose
New Launch Configuration.
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)
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.
Select break points in the code you're are going to run.
From your command line, append the following to your maven command.
For example, to debug the tests run by the Maven lifecycle
mvn install -Dmaven.surefire.debug
Wait for Maven to pause its execution and display the message,
Listening for transport dt_socket at address: 5005
Attach the debugger to the running maven by selecting the "Maven Surefire" debug configuration created above.
Select break points in the code you're are going to run.
Run Maven in debug mode, e.g
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
At line 30, you'll find this,
@REM set MAVEN_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000
Uncommenting the line by deleting
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
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
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.
1. Why can't I just use Generic Debugging even for my tests?
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.
2. Will using argLine parameter of maven-surefire-plugin work instead of the -Dmaven.surefire.debug ?
2. Yes. maven.surefire.debug acts like a shorthand version of argeLine=<debugging configuration>. So in most cases, using maven.surefire.debug be enough.