Geronimo Eclipse Plugin FAQ

This FAQ is broken down into two sections. The developers FAQ provides information for developers interesting in contributing to the eclipse-plugin. The User's FAQ is targeted for users to provide answers to common question on how to install and use the eclipse plugin.

What is the Geronimo Eclipse Plugin?

The Geronimo Eclipse plugin provides a server adapter and other Geronimo development specific features that is built on the Web Tools Platform. The primary usage scenario for the plugin allows users to develop, build, and test application and services for the Geronimo Application Server.

Developers FAQ

How do I build the Geronimo Eclipse Plugin?

The root of the source tree for the eclipse plugin is located in an svn repository at

https://svn.apache.org/repos/asf/geronimo/devtools/eclipse-plugin/

The following environment variable needs be set to properly configure the JVM to meet memory requirements.

MAVEN_OPTS="-Xms512m -Xmx512m -XX:MaxPermSize=256m"

On Windows use the following command to set the environment variable (note that double quotes should not be used):
set MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=128m

To build the latest source (assuming you have maven2, ant, and subversion installed) invoke the following to check out the source of trunk:

svn co https://svn.apache.org/repos/asf/geronimo/devtools/eclipse-plugin/trunk/ geronimo-eclipse

Then, from within the geronimo-eclipse directory, simply invoke "mvn". This will run through the entire build process from compilation to generating the distributions.

You do not need to manually download eclipse or the web tools project to build. This is taken care of for you automatically during the build process.

Why not use the Eclipse headless PDE?

The Eclipse Plugin Development Environment is capable of running in a headless-mode to build eclipse features and plugins. This is the primary means of building eclipse plugins. However, in an effort to provide a uniform build environment across all of Apache Geronimo, it was a community decision to provide a fully mavenized build process for the eclipse plug-in.

Can you explain the contents and directory layout of the source tree?

Can I use the Import Existing Project wizard in Eclipse to import the plug-ins into my Eclipse workspace for development?

Yes, however a full m2 build will need to be run from the command line first. In order to successfully import the projects into eclipse, some EMF code generation needs to be run by maven to generate model code for the Geronimo schemas. This generation code is the used by other plugins. If this code is missing, the imported projects will have compilation errors that are not resolvable by PDE.

Can I use another IDE such as NetBeans or IDEA to develop eclipse plugins?

It is not recommended. Eclipse provides a plugin development environment (PDE) and one of its key features is the creation of a specific type of launch configuration that allows plugins to be both run and debugged against a target platform. This configuration, commonly known as a runtime-workbench, launches your target platform plus any development plugins you have in your workbench. It would be difficult, if not impossible, to set up another IDE to do this.

How are dependencies to other eclipse plug-ins handled?

Since each bundle-manifest already provides dependency information to other bundles, these dependencies do not have to be respecified in each project's POM. During the build, the "Require-Bundle" attribute in each bundle manifest is processed and a maven dependency is added dynamically for every entry. During this process, each of these bundle dependencies is located inside the specified target eclipse distribution (specified in the root pom) and then installed into the local m2 repository for use by maven's dependency resolver. So essentially this mimics the PDE builder in that we build against a target platform rather then against individual dependencies.

Where are the eclipse plugin dependencies?

Since the eclipse platform, and other required top level Eclipse projects do not publish each plugin independently to a remote maven repository, the maven build process pulls down full distributions of these required projects, unzips them to create a "target-platform". This is done intelligently so that the target platform is not generated on every build and only if required versions of the Eclipse projects have changed, or if the "target-platform" has been altered.

Each downloaded zip distribution is placed in ~/.m2/repository/eclipse/distributions.
The target platform used is located at ~/.m2/repository/eclipse/eclipse.

The download URL's are for each required distribution is specfied in the root POM as such.

<platformDriver>R-3.2-200606291905/eclipse-SDK-3.2</platformDriver>
<platformUrl>http://download.eclipse.org/eclipse/downloads/drops/${platformDriver}</platformUrl>
<emfUrl>http://download.eclipse.org/tools/emf/downloads/drops/2.2.0/R200606271057/emf-sdo-xsd-SDK-2.2.0.zip</emfUrl>
<jemUrl>http://download.eclipse.org/tools/ve/downloads/drops/R-1.2-200606280938/JEM-SDK-1.2.zip</jemUrl>
<gefUrl>http://download.eclipse.org/tools/gef/downloads/drops/R-3.2-200606270816/GEF-SDK-3.2.zip</gefUrl>
<wtpUrl>http://download.eclipse.org/webtools/downloads/drops/R-1.5.0-200606281455/wtp-sdk-R-1.5.0-200606281455.zip</wtpUrl>

These URLs are then used by the plugin configuration also in the root POM.

<plugin>
  <groupId>org.apache.geronimo.devtools</groupId>
  <artifactId>maven-geronimodevtools-plugin</artifactId>
  <configuration>
    <platformUrl>${platformUrl}</platformUrl>
    <urls>
      <url>${emfUrl}</url>
      <url>${jemUrl}</url>
      <url>${gefUrl}</url>
      <url>${wtpUrl}</url>
    </urls>
    <eclipseHome>${settings.localRepository}/eclipse/eclipse/</eclipseHome>
  </configuration>
  <executions>
    <execution>
      <id>create-eclipse-image</id>
      <phase>validate</phase>
      <goals>
        <goal>download</goal>
      </goals>
    </execution>
  </executions>
</plugin>

OK, I've build successfully, now what?

After building, the projects are ready to be imported into a eclipse workspace. Launch Eclipse with a clean workspace. First we'll need to set up our target platform. The target platform is the eclipse image generated by the maven build process. In your workspace preferences select the target platform and enter the path to the generated target platform. This path by default is ~/.m2/repository/eclipse/eclipse.

Now we are ready to import projects into out workspace. Begin by launching the "Existing Projects into Workspace" import wizard.

Select the location of the plugins directory on your filesystem of your source tree. For example, .../geronimo-eclipse/plugins. The wizard will automatically preselect all the projects found. Select Finish.

The projects will then be imported into your workspace and your Package Explorer view in the Java Perspective will look like the following:

I've successfully imported the projects into my workspace for development. How do I setup a launch configuration to test code changes?

From the menu, select Run.. This will launch the Run configuration page. Create a new Eclipse Application configuration and name it anything to identify it as the Geronimo Eclipse Plugin. The defaults will launch every plugin in the target platform plus all open plugin projects in your workspace. This and the other defaults are sufficient.

Mac OS X Users Select the Arguments tab and set the -Dorg.eclipse.swt.internal.carbon.smallFonts argument in the VM Argument's section for a better display in the runtime workbench.

How to I test the binary distributions?

During development you'll want to run within a runtime workspace and not use the distributions. However at times, when the distributions need to be tested they can be easily done so with your target platform.

User FAQ

How do I install the geronimo eclipse plugin?

What is a WTP project facet, and what facets does the Geronimo plugin provide?

What is the difference between creating a Geronimo runtime and a Geronimo server?

Do I need to download Geronimo?

What is the server editor?

What is a test environment?

How can I edit geronimo deployment plans?