Building Eclipse Plugins with Maven: Tycho

Yesterday’s post was in response to a question from Anders Nawroth of the Neo4J effort, and today’s post is no different.  On Tuesday (or maybe it was Monday), Anders asked the neo4j-users list whether it made sense to build the neo4j eclipse plugin with Maven.

I have looked into building Neoclipse using Maven, but at the moment I’m not convinced there are more advantages then disadvantages in this case.  Building Eclipse plugins and products has quite many quirks. With increasing use of product configuration options, the number of build quirks increases as well. There seems to be no really automated build system for Eclipse plugins/products, even when using maven you have to install and update the dependencies manually (the Eclipse artifacts are not deployed to a maven repository).

Sonatype is busily working to address these gaps, and we already have some solutions you can use to start building your Eclipse plugins in Maven.   Igor Fedorenko has been working on Tycho and Maven to create a system to facilitate OSGi and Eclipse development in Maven, and m2eclipse is currently built using Tycho.   To prove that Tycho is a viable path for build the Neoclipse plugin, I took some time yesterday to generate Maven pom.xml files with Tycho and build an update site for Neoclipse.

A Basic Summary of Tycho

The general idea of Tycho is that it acts as a bridge between Maven and OSGi.  It supports a number of usage scenarios and is under active development.   It can be used in a manfiest-first mode which builds a Maven POM from an OSGi manifest and it can also be used in a pom-first mode in which Tycho is responsible for generating an OSGi manifest from a Maven POM.  Future plans include the ability to build a project usin Maven/Tycho without requiring the presence of a Maven POM, and there is active work under way to allow Nexus Maven repository manager to interact with Eclipse update sites and p2 repositories, that would allow Tycho to consume artifacts from those repositories.   If you are looking for a more in depth explanation of Tycho, check out the Tycho Project Overview.

If you are looking for a solution to automate Eclipse builds with Maven, look no further, Tycho is your answer.  In this post, I’m going to walk you through the process of configuring a Maven build for a real Eclipse plugin.   This process involves the following, high-level steps:

1. Configuring Eclipse
2. Downloading Tycho
3. Checking out Eclipse Plugin Source from Subversion
4. Generating Maven POMs using Tycho
5. Packaging Your Eclipse Plugin and Generating an Update Site with Maven

At this point in the development of Tycho, you’ll have to point the system at an installation of Eclipse, your targetPlatform.   Let’s get started.

Configuring Eclipse

Tycho currently builds Maven pom.xml using a local installation of Eclipse which should contain the Plugin Development Environment (PDE) and other Eclipse components your specific plugin depends on.   Future versions of the Tycho product will likely interrogate remote p2 repositories and Eclipse update sites, but for now we have to configure a local Eclipse Target Platform with the necessary components.  For this particular example, you’ll need to install Eclipse 3.4 and download a few plugins that the Neoclipse plugin depends upon.   For more information about what Neoclipse requires, see the Neo4J Wiki Page for Neoclipse. These steps are also needed when you need to work with Neoeclipse code using Eclipse PDE.   You need to:

1. Download and install Eclipse 3.4 if you don’t already have it installed.
2. Neoclipse has a graphical editor component which relies on GEF.  To build the plugin, you’ll need some of the Draw2D components.   The easiest way to install this particular plugin is not via the standard Eclipse update manager.  You should download GEF ALL distribution for Eclipse 3.4 from the GEF Download page.   The direct link for the GEF-ALL distribution is here.
3. To install the GEF-ALL distribution, unpack the ZIP file to a directory and then copy that directory to your Eclipse installation.  This will install all the necessary features and plugins that neoclipse depends on.
4. As usual, I would recommend installing both the m2eclipse plugin and the Subclipse plugin.   These are two plugins I almost always need:
   1. m2eclipse update site: http://m2eclipse.sonatype.org/update (or if you want to use the latest stable DEV build http://m2eclipse.sonatype.org/update-dev)
   2. Subclipse Update site: http://subclipse.tigris.org/update_1.4.x

I’m on a Mac, so I usually install my eclipse distribution in /Applications/eclipse.   For the remainder of this document, if you see /Application/eclipse, you should substitute your own eclipse installation directory.

Downloading and Configuring Tycho

At this point, you have Eclipse installed and configured with the necessary plugins to build the Neoclipse plugin.   Now you need to download and configure Tycho.  Tycho contains a development version of Maven 3.0 that has been extended to allow for Tycho to interact with the the OSGi components and format of the plugins directory of your Eclipse plugin. In the future versions you could use regular Maven 3.0 and use Tycho as any other Maven plugin.

1. Download Tycho from http://docs.codehaus.org/display/M2ECLIPSE/Tycho+builds.  I downloaded the latest DEV build, and I installed it in ~/programs/tycho – Tycho includes a development SNAPSHOT of Maven.
2. Set M2_HOME to point to ~/programs/tycho.   If you don’t do this and you already have Maven 2 installed, you are going to run into errors and issues if you try to run either Maven or Tycho.   I usually set M2_HOME to point to my Tycho installation by running “export M2_HOME=~/programs/tycho” in bash.

Once Tycho is configured, you are ready to generate Maven POMs from your Eclipse plugin.

Generating Maven POMs with Tycho and Building an Update Site

The demo script for Tycho uses a contrived a demo project called tychodemo.zip which contains a simple Eclipse plugin.   I wanted to demonstrate that Tycho is ready to be used today with a real Eclipse project.    This project is the Neoclipse plugin for Eclipse that allows users to interact with a Neo4J database in the Eclipse IDE.

1. Change directories to a working directory.  I usually do all of my coding in a ~/svnw directory which is segmented by focus.   So, I check out Open Source projects like neo4j in a ~/svnw/os directory: cd ~/svnw/os
2. Checkout the source code for the neoclipse Eclipse plugin with Subversion: svn co https://svn.neo4j.org/components/neoclipse/trunk neoclipse
3. Change directories into the neoclipse directory: cd neoclipse
4. Generate a set of Maven POMs from the Neoclipse source using Tycho: ~/programs/tycho/bin/mvn -X org.codehaus.tycho:maven-tycho-plugin:generate-poms -DgroupId=tycho.demo -Dtycho.targetPlatform=/Applications/eclipse

At this point, you’ll have pom.xml files in all of your plugins and at the top level.   Tycho has generated a multi-module Maven project that references components in your targetPlatform, specified using “tycho.targetPlatform” property on the command line.  Tycho doesn’t need Eclipse to be running, all it needs is access to the Eclipse directory so that it can resolve components such as the Eclipse Plugin SDK at the GEF plugin installed in the previous section.

To build the update site, run:  ~/programs/tycho/bin/mvn package -Dtycho.targetPlatform=/Applications/eclipse You should then have an update site in ./org.neo4j.neoclipse.updatesite/target/site

To avoid specifying tycho.targetPlatform property every time, it could be added to your settings.xml. For example:

...
  <profiles>
    <profile>
      <id>tycho.default</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
        <tycho.targetPlatform>/Applications/eclipse</tycho.targetPlatform>
      </properties>
    </profile>
  </profiles>
...

UPDATE (9:21 AM CST): Eugene Kuleshov just sent in a bunch of edits and improvements which were incorporated. Removed the section about adding the repository as it should already be in the public group hosted on Sonatype’s Nexus repository.

How-To eclipse, eclipse plugin, Maven, neo4j, OSGi, Tycho