Working with Maven Multi-Module Projects in Eclipse and SVN

18 June 2012

I'm a recent convert to Maven. After I got used to their conventions such as paths "src/main/java" and "target" I was delighted by how little work is required to get a Java project on its feet and built. I especially like the ability to name the required jar files (dependencies) by name and version number and have maven go fetch the jars from its central repository. No more jar files checked in to our version managment system! That was a pet peeve of mine for far too long and maven completely ends it. And via M2E the Eclipse integration works pretty smoothly.

Now I need to move up to a multi-module maven project, a nested collection of one parent project and many submodule (child) projects in subdirectories. The main reason is to allow the subprojects to be packaged separately; some will be WAR files, others plain-old jar files. The maven "reactor" (still don't like that name) figures out which child project provides which feature, and sets the build order so the providers are built ahead of the consumers. That's quite nice too. But I want to keep working in Eclipse. In other words, the submodule src/main/Java folders should be first class Eclipse java areas so all the various JDT goodies work as expected.

Background: Maven is happy with either shallow or wildly deeply nested projects. A nested Maven project has subdirectories with subprojects (ignoring for the moment tricks where some people use ".." in path names to flatten their hierarchies). Eclipse doesn't understand nested projects and from what I read in various forums it seems the Eclipse people are not accepting any feature requests to go in this direction. The only way Eclipse works with Java classes is via a series of top-level projects. And the Maven people have figured out how to make it all happen.

For starters in Eclipse I created my first submodules with the feature Maven -> New Maven Module Project (right click on any Maven project). This adds a new submodule and modifies the parent POM appropriately. And most interestingly a new top-level project appears in the workspace that is some kind of magic link to the submodule! But after a check-in to Subversion, clean workspace, then check back out again, those magic top-level projects did not appear. Uh oh.

So the challenge was making it all work in Eclipse properly after a SVN checkout. (I know that the Juno release is soon but I'm still using Indigo.) A lot of googling yielded many comments, most not helpful. I finally turned up some assistance at stackoverflow:
Eclipse + Subversion (subclipse) + Maven (m2eclipse) multi-module project

The secret here is that I had to use a Maven-specific feature to check out the Maven superproject from SVN. But first I had to install the connector so the M2E plugin could talk to the Subversive plugin. Here's how to get all set up.

  1. Any Maven project requires that the m2eclipse (AKA m2e) plugin is installed in your Eclipse. Download it from the Eclipse update site as follows:
  2. Checking out Maven multi-module projects properly from SVN requires a m2e connector. Add the connector in Eclipse as follows:

Once all the required plug-ins were installed, I was ready to use the Maven SCM connector to check out a Maven multi-module project from SVN. In the SVN Repository Exploring view, I browsed the tree until I could see my parent Maven project, right clicked on it, then picked Check Out as Maven Project. Clicked Next then Finish. The m2e plugin created a top-level Eclipse project for every submodule in the parent project. Each had proper Java source folders with the Eclipse JDT working properly!

After the first checkout I had to run maven with the goal "install" to build the jars provided by the submodules and and copy them to my local repository. Then the dependencies that Eclipse requires were satisfied.

And that's what I had to do for a multi-module Maven project to play nicely in my Eclipse Indigo. Hope this helps someone, please drop me a line if it does.

Blog index