How to Use Google Plugin for Eclipse with Maven

Update Mar 28, 2012: Thanks to improved Maven integration in Google Plugin for Eclipse, this blog post is very out of date. Please see WorkingWithMaven instead for instructions on using Maven with Google Plugin for Eclipse.

As part of the GWT team's ongoing effort to address the needs of the Maven community, the Google Plugin for Eclipse (GPE) team is working to improve interoperability with Maven in future releases. Plugin version 1.3.3 makes it possible to use Maven in a GPE project with a little tweaking, and future versions aim to improve this experience. There is already good support from the open source community for using Maven with GWT and/or App Engine projects; however, it has been difficult to enable both Maven and GPE for the same project. This article explains how to do that. It assumes you already have some Maven knowledge.

Working with GWT and GAE in Maven

First, here are a few tips on using Maven with GWT and GAE.
The open source community has written Maven plugins for both GWT and App Engine which wrap the native development tools for these platforms.

• maven-gae-plugin provides Maven goals to run, debug, deploy, and rollback a GAE application as well as a handful of utility goals. In addition, the plugin automatically retrieves all GAE runtime dependencies from the plugin's SVN repo (Google is working on publishing these dependencies to the central Maven repo, as well).
• gwt-maven-plugin from codehaus.org provides Maven goals to compile GWT applications, and run or debug in hosted mode using the dev mode console.

Both projects provide Maven archetypes to generate a pom.xml and project skeleton. In addition, you can find a GWT+GAE+Roo sample POM within the Expenses sample project in GWT trunk. It contains everything you need to build a GWT 2.1 app (as of 2.1.0 M3) with Spring Roo and deploy to App Engine. If you're not using Spring, you can remove the Spring dependencies.
The documentation for each plugin lists all of the Maven goals available, but we'll briefly look at the most common:

• mvn gae:run starts the App Engine development server.
• mvn gae:deploy deploys your application to App Engine.
• mvn gwt:run runs your GWT app in hosted mode using the standalone dev mode console. If you're using maven-gae-plugin, it will also invoke gae:run.
• mvn gwt:debug runs your GWT app in hosted mode and additionally enables the debugger port hook so you can debug in Eclipse as a Remote Java Application on the standard debugger port (8000). It is generally easier, however, to launch the debugger within Eclipse using GPE. We'll look at how to enable that shortly.
• mvn gwt:compile compiles your GWT app for production.
• mvn eclipse:eclipse creates an Eclipse project that you can import into Eclipse. The sample POM referenced above contains configuration for the maven-eclipse-plugin which adds the gwt and gae project natures used by Google Plugin for Eclipse. After you run Maven eclipse:eclipse, you can import your project into Eclipse using File | Import | Project | Existing Project.

Using the goals provided by the GWT and GAE Maven plugins, it is not necessary to use the Google Plugin for Eclipse at all, as you can use Maven instead to run / debug / deploy. However, GPE provides tighter integration with Eclipse Run / Debug launch, code completion, warnings and errors, etc., so it's useful to enable it also.

Enabling Google Plugin for Eclipse to work with an existing Maven project

If you have an existing Maven project in Eclipse and want to enable GPE functionality, follow these steps:

1. In Eclipse, open your project's properties (Alt+Enter or right-click, Properties)
2. Under Google | App Engine, select the version of the App Engine SDK you're using. GPE is not yet able to use the version defined in your Maven POM, so you may need to download your SDK version using the Eclipse software updater (see http://code.google.com/eclipse/docs/download.html)
3. Under Google | Web Toolkit, likewise select the version of the GWT SDK you're using. As with the App Engine SDK, install it via the Eclipse plugin update site if needed.
4. Under Google | Web Application, check the "This project has a WAR directory" box and point it to your project's src/main/webapp directory. This is the standard WAR source folder for Maven Web projects. Be sure that the "Launch and deploy from this directory" box is NOT checked.
5. Under Java Build Path, select the Order and Export tab and move all Maven dependencies to the BOTTOM. Otherwise, GPE will see the App Engine and GWT SDKs from the Maven repo on the build path and complain that they are not valid. This is because GPE expects a specific SDK structure used to enable other tooling.
6. Also under Java Build Path, select the Source tab and ensure that the Build output directory is enabled and pointing to target/your-project-name/WEB-INF/classes. If you created the project with mvn eclipse:eclipse, this should be done for you automatically.
7. Finally, and this is very important, the first time you launch your project using Run As | Web Application (or Debug), you will be prompted to select the war directly. This is NOT src/main/webapp, but rather the WAR output folder, which is target/your-project-name. If you make a mistake, simply go to Run | Run Configurations... and remove any old configurations for the project. GPE will then ask you again next time you try to Run As | Web Application.

Mavenizing an existing GPE project

To use Maven with an existing GPE project, follow these steps:

1. Create a pom.xml using one of the project archetypes or sample POM discussed above. Make sure it contains configuration for gwt-maven-plugin, maven-eclipse-plugin, and maven-gae-plugin (if you're using App Engine).
2. Maven projects use a different layout than the default GPE project, so create folders for your Java code (src/main/java) and static resources (src/main/webapp).
3. Move all source files under the GPE-created war directory into src/main/webapp. These include any config files (web.xml, etc.) under war/WEB-INF and static resources such as images and CSS. After you've moved the source files, you can delete the war directory, as Maven will create output folders for your GWT modules under the target directory, not the war directory.
4. Add Maven dependencies in your pom.xml for each jar that had been in WEB-INF/lib.
5. Run mvn clean gae:unpack war:war in the pom.xml directory. This will unzip the App Engine SDK in your local maven repo and copy static resources from src/main/webapp into target/project-name, where GPE expects to find them when configured as above.
6. Run mvn eclipse:clean eclipse:eclipse in the project directory to recreate your Eclipse project file, then Refresh it in Eclipse (select project and press F5 or right-click, Refresh).
7. Follow the steps in the previous section to enable GPE support with Maven.

Let me conclude with a hearty thank you to everyone who has contributed to the development of maven-gae-plugin and gwt-maven-plugin. Your contributions are an indispensable part of Google's ability to better meet the needs of the Maven community.