Sebastian Bauer's Homepage

[English|German|Spanish][english|deutsch|español]

Tutorials

Here, you will find various tutorials. If you like one of them, I would be happy about a small donation. If you have feedback, please send it to mail@sebastianbauer.info. At this time, all of this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. Creative Commons License

Building Eclipse Plugins with Maven and Tycho

Sebastian Bauer

February 29, 2012

Abstract

The purpose of this tutorial is to show how Maven can be used for building Eclipse plugins. We will develop a simple plugin that enhances Eclipse with menu entries to rewrap given text passages. We configure the plugin such that it is build using Maven and Tycho.

Contents

1 Introduction

In this tutorial, we develop a plugin that enhances the Eclipse framework with a function to rewrap a paragraph of text that is currently selected in a text editor. We will implement two variants of this feature. For the first variant, always a fixed but user-configurable line length is used. A word that spans beyond this limit is placed together with the remaining words in the next line. The second variant is a generalization of the first variant, such that a user-configurable tolerance number is taken into account. The line length is no longer fixed but can vary by the given amount in order to minimize the number of additional spaces implied by the rewrapping.

The focus of this tutorial is, however, not the creation of plugins within the Eclipse framework, but how Maven can be used to build the plugin rather than using the Plugin Development Environment (PDE) tools provided by Eclipse directly. This is especially convenient when the plugin is developed in a continuous integration environment where manual PDE is not applicable. We will make use of Tycho for this purpose, which is a plugin for Maven designed exactly for this purpose.

Throughout the tutorial, we assume that the reader is familiar with the Eclipse framework but we don’t assume that the reader is familiar with Maven. Yet, this is also no introduction to Maven in general. We will just consider enough stuff to be able to build Eclipse plugins.

2 Installing Requirements

As this tutorial is based on Eclipse, we need an Eclipse installation. Version 3.7 from the Indigo release train is used here. For convenience, we also make use of th Eclipse plugin Maven Integration for Eclipse. In order to install it, use the Eclipse market place, click on the Install button for the feature Maven Integration for Eclipse as shown in Figure 1, and follow the instructions.


PIC
Figure 1: The Eclipse Marketplace.


For a seamless integration of Maven and Tycho into Eclipse, a Tycho m2e connector is needed. Installation of m2e connectors is accomplished in the preferences Window ¿ Preferences ¿ Maven ¿ Discovery by pressing the Open Catalog button and activating the Tycho Configurator as indicated in Figure 2. Click on Finish and follow the installation instructions.


PIC
Figure 2: The m2e Marketplace.


3 Developing the Plugin

For Eclipse plugins, it is common practice to organize the code in at least four projects. In the first project, we locate the plugin code, in the second project we locate the test code, in the third project, the bundle or feature is specified, whereas the fourth project represents the update-site of the plugin. We follow this convention also when building with Maven. In particular, each project is organized as a Maven module with a dedicated package type given via the packaging XML tag in the pom.xml file: eclipse-plugin, eclipse-test-plugin, eclipse-feature, and eclipse-repository respectively.

In order to wrap all modules, Maven requires us to specify a parent module. The parent module does not necessarily need to be represented physically by the parent directory and therefore can live everywhere. We will implement this Maven module as an Eclipse project of its own with the package type being set to pom.

3.1 Creating and Configuring the Projects

Before the development of the plugin can really start, there is a bit of infrastructure to set up. Although the following description aims to create the infrastructure for our justify project, the steps can be easily generalized to setting up other projects.

3.1.1 Creating the Parent Module

We begin with creating the project that represent the parent module. First, you need to invoke the New Maven Project wizard, to which you will get access using the menu entry File ¿ New ¿ Project... as given in Figure 3.


PIC
Figure 3: New Project.


Choose from the list of wizards Project ¿ Maven Project as indicated in Figure 4. Press Next ¿.


PIC
Figure 4: Invoking the New Maven Project wizard.


On the first page, activate the checkbox for Create a simple project in order to skip the so-called arch type selection, which would allow you to select a special project template. Press Next ¿.


PIC
Figure 5: Basic Settings for the Maven Project.


In the second page, we shall enter the project’s details. In particular, the Group Id is similar to package names in Java, thus it is recommended to use a URL in reverse order. For this example, however, enter justify. The Artifact Id is the name of the project. Enter justify.parent as this project will become the parent project. The Version field can be left as it is, i.e., 0.0.1-SNAPSHOT, but the field Packaging has to be set to pom for in order to specify that this project consists only of a pom.xml file, i.e., is a parent project. The fields Name and Description can be filled with information that only as a meaning for users but here we leave them blank. We also leave the other fields blank and press Finish to create the project.


PIC
Figure 6: Details of the Maven Project.


A new project labeled justify.parent should appear now in the Navigation view. We need to configure the project to use the Tycho plugin when building with Maven. To do so, open the pom.xml file of the new project. The Maven POM Editor should be shown, in which we switch right to the pom.xml register in order to directly deal with XML code.

In order to enable Tycho for the Maven build, we are required to add the tycho-maven-plugin from group org.eclipse.tycho as an extension of the build process. It is generally enough to specify the details of an Maven plugin as it will be automatically downloaded and cached when the build is invoked. As the details of the plugin also consists of a version identifier, we first declare a property called tycho-version to contain a particular version, which in this tutorial is 0.14.1. This approach allows us to easily change the version later by only altering the property. The following snippet represents these details translated to Maven XML:

  <properties>  
     <tycho-version>0.14.1</tycho-version>  
  </properties>  
 
  <build>  
     <plugins>  
        <plugin>  
           <groupId>org.eclipse.tycho</groupId>  
           <artifactId>tycho-maven-plugin</artifactId>  
           <version>${tycho-version}</version>  
           <extensions>true</extensions>  
        </plugin>  
     </plugins>  
  </build>

The contents of the snippet should be added to the opened pom.xml file.

For successfully building an Eclipse plugin, many prebuild binaries and dependencies such as org.eclipse.core.runtime or org.eclipse.ui have to be taken into account that provide the context of the build. Recall that the update URL for Eclipse Indigo is http://download.eclipse.org/releases/indigo. As with all Eclipse repositories, it follows the so-called p2 layout. Luckily, a repository like this can be used straight also within Maven by adding following lines to the pom.xml.

  <repositories>  
   <repository>  
      <id>eclipse-indigo</id>  
      <layout>p2</layout>  
      <url>http://download.eclipse.org/releases/indigo</url>  
   </repository>  
  </repositories>

3.1.2 Creating the Plugin Module

The plugin project, in which the majority of the Java code will be written, is created as usual. That is, use the New Plug-in Project wizard to create the plugin. The plugin should be called justify. In the second page, make sure that the ID field is filled with justify and the Version field gets the contents 0.0.1.qualifier. See Figure 7 for how it should look like. We then press Finish as we don’t need any particular template.


PIC
Figure 7: New Plug-in Project.


In the next step, we will convert the just created justify project to a sub module of the previously created parent module. This is easily accomplished via entry Configure ¿ Convert to Maven Project of the project’s context menu as indicated in Figure 8.


PIC
Figure 8: Convert a Project to a Maven Project.


In the appearing dialog we are not able to define the parent module. Therefore, we leave the entries as they are and press Finish. By this event, a little decorator showing an M should appear in the navigation view for the project indicating that it is a Maven project now. Also, the newly created pom.xml file should now be open to allow further adjustments, which we will do in the following.

In the Overview register, change the contents of the Packaging field to eclipse-plugin. This is one of the package types that Tycho provides. If the pom.xml file is saved at this stage, Eclipse is not aware of this type and shows an error message. We need to configure the pointer to previously created parent module, which has all of the information. To do so, we enter in the Parent area for Group Id the contents justify. For Artifact Id we enter justify.parent and for Version we type in 0.0.1-SNAPSHOT. It is also important to specify the Relative Path of the parent pom.xml file, which is ../justify.parent/pom.xml in our case. Finally, we should clear the Group Id and the Version fields of the Artifact area to reduce redundancy, as this information now comes from the parent module. Figure 9 depicts the contents of the Overview register. Don’t forget to save newly entered information.


PIC
Figure 9: POM Editor for the Plugin.


Before we test the current setup, we will add the plugin project as a sub module for the parent project. For this purpose, open the pom.xml file of the parent project, i.e., justify.parent/pom.xml. In the Modules area within the register Overview, press the Add... button. Make sure to have a checkmark before the project justify and press OK. The list within the Modules area should now contain a single line ../justify. Finally, save the changes.

3.1.3 Testing the Configuration

At this stage, it makes perfect sense to test the current configuration. For this purpose, select the justify.parent project and select use Run ¿ Run As ¿ Maven build, e.g., using the Run button of the toolbar as shown in Figure 10.


PIC
Figure 10: Invoking the Maven Build.


After the launch configuration dialog has been opened for the new Maven build, enter clean verify within the field Goals. This means that the clean lifecycle and the verify lifecycle should be performed. The latter implies a lot of other lifecycles, such as building the package and doing integration tests. Press Run to invoke the Maven build. Within the Console one can notice now that a lot of stuff is being downloaded. After a while, the build finally concludes hopefully indicating a success as in Figure 11


PIC
Figure 11: First successful build.


3.1.4 Creating the Test Module

The next step is to create the test module. Please create a new Plug-in project as before and name it justify.tests. Make sure that the Version field is again 0.0.1.qualifier. Then convert the project to a Maven module via Configure ¿ Convert to Maven Project (see Figure 8) and fill in similar information as before, but make sure that Artifact Id is now justify.test. Generally, it is important that the Artifact Id matches the ID of the project, which corresponds to the Bundle-SymbolicName entry in the MANIFEST.MF file. Also, type eclipse-test-plugin in the Packaging field. Once the project has been converted, note that the package type is not known yet in the context of the this project. This problem can be solved by specifying the project justify.parent as parent project, as we also did before.

An alternative way to specify the parent module is to add the new module as a submodule in the parent project as done before, i.e., using the Add... button in the Modules area in the POM editor of the parent project, but checking Update POM parent section in selected projects in the list of modules to be added, as can be seen in Figure 12.


PIC
Figure 12: Updating POM parent section.


Of course, it makes again sense to test the current setup. For this purpose, invoke the previously created launch configuration. Simply use Run ¿ justify.parent as indicated in Figure 13.


PIC
Figure 13: Invoking Maven Build.


This time, the build should fail. In the Console view we read somewhere at the bottom:

Failed to execute goal org.eclipse.tycho:tycho-surefire-plugin:  
   0.14.1:test (default-test) on project justify.tests: Could  
   not determine test framework used by test bundle  
   MavenProject: justify:justify.tests:0.0.1-SNAPSHOT @  
   D:\workspace-tutorial\justify.tests\pom.xml

This simply means that Maven doesn’t know about which test framework to use. As Tycho evaluates the dependencies of the plugin, it is enough to add the test framework as a plug-in dependency. In this tutorial, JUnit 4 will be used. Therefore, please add org.junit with a major version number greater then 4 as a dependency of the test plugin. This is best accomplished via the Plug-in Manifest Editor on Dependencies register. Also add the plugin to test, i.e., justify, as a dependency. The result is shown in Figure 14.


PIC
Figure 14: Test Plugin Dependencies.


A new Maven build is still not completed successfully, because the integration test reports test failures. The reason for behavior is that no test was implemented so far. As there is still some infrastructure to set up before we can implement anything, we go for a dummy test case. Add the following DummyTest class to the package justify of the justify.tests project.

package justify.tests;  
 
import org.junit.Test;  
 
public class DummyTest  
{  
  @Test  
  public void testDummy()  
  {  
  }  
}

With that change, the Maven build should complete successfully.

3.1.5 Creating the Feature Module

A feature project is a container for all plugins that should be part of the distribution. Feature projects are created using a dedicated wizard that is brought up, for instance, via a menu entry File ¿ New ¿ Feature Project. Figure 15 shows important settings that this tutorial assumes for the Justify feature.


PIC
Figure 15: Wizard to Create a New Feature.


Plugins that should be packaged into the feature can be selected in this wizard as well by clicking on the Next ¿ button. As this page lacks a search capability, it is recommended to use the register Plug-ins of the Feature Manifest Editor for the newly created feature. Regardless of how a plugins is added to a feature, make sure that our justify plugin is listed there. Also, do not include justify.test as do not want to distribute the test plugin.

After the successful creation and configuration of the feature project, we need to convert it to a Maven module. This can be done in the same way as before. This time, type in eclipse-feature as package type. Make sure that the project is listed as a module of the parent project and that the pom.xml file references the parent project. Figure 16 shows the contents of the Overview register. You may want to verify that the current setup works by invoking the Maven build.


PIC
Figure 16: Configuration of the Feature POM.


3.1.6 Creating the Repository Module

The last thing that we need to set up in order to complete the skeleton of our plugin is the project describing the update site. Although Eclipse offers a New Update Site Project wizard for this purpose, we won’t use it, as this particular type of project is deprecated by recent versions of Tycho. Therfore, create a plain project, which can be found in the General category and call it justify.repo.

Convert this project to a Maven project with package type being set to eclipse-repository, enter the pointer to the parent project, and add the new project as a module of the parent project. When building this repository project, Tycho needs to know, which features should go in. This is done by creating a Category Definition file named category.xml. Fill it with following contents:

<?xml version="1.0" encoding="UTF-8"?>  
<site>  
   <category-def name="justify" label="Justify Tutorial"/>  
   <feature url="features/justify.feature_0.0.0.qualifier.jar"  
      id="justify.feature">  
      <category name="justify" />  
   </feature>  
</site>

If you are done, you can invoke the Maven build. And assuming that the build is successful, you’ll find a file called justify.repo.zip in the target directory of the project. This is the master archive of the plugin that can be added to any Eclipse installation. The contents of this archive or of the repository directory is ready to be deployed on your Web server hosting the plugin.

3.2 Coding the Plugin

Here, you will find soon the steps necessary to actually code the plugin.

4 License

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.

By judgement of May 12, 1998, the Landgericht Hamburg decided that by attaching a link, you might be held responsible for the contents of the linked page. According to the Landgericht, this can only be prevented by explicitely expressing dissent from this contents. So for all links from my page to other pages in the internet is applied: I emphasize that I do not have any influence on the design and the contents of the linked pages. I therefore deny responsibility for the complete contents of all pages linked from my homepage. This declaration is valid for all links placed on my homepage without any exception.