Working with the Eclipse Tycho Plug-In

The Eclipse Tycho plug-in enables building Eclipse plug-ins with Maven. For more information, see Eclipse Tycho.

In Eclipse, when you create a plug-in project or a feature project, it is not created as a Maven project. Instead of using Maven, Eclipse PDE uses other metadata files such as manifest.mf, build.properties, plugin.xml and feature.properties. Tycho uses native metadata for Eclipse plug-ins and uses the pom.xml file to configure and drive the build.

The support of Eclipse PDE makes it much easier to develop a plug-in for Eclipse. This not just a vanilla OSGi bundle, but a plug-in for Eclipse, so it should be possible to run and debug it using the Eclipse IDE. Therefore, you should create a plug-in project using the PDE. You can then convert it to a Maven project (only if you need to build automation with Maven).

Setting up the IDE

Download the Eclipse Luna SR2 Java EE version for your platform.
Install the latest Dev Studio Kernel to it (Help → install new software: point to p2 repo).

Creating an Eclipse Plugin

This guide assumes that you have a basic knowledge in developing Eclipse plug-ins. If you do not have any previous experience, follow the Extending the Eclipse IDE - Plug-in development tutorial .

If you have previous experience in developing OSGi bundles with the maven-bundle-plugin and you plan to use Maven as the build tool for build automation of your plug-ins, we strongly suggest you have a good understanding of the following:

PomFirst vs ManifestFirst Development
Eclipse Tycho
Maven-bundle-plugin vs Tycho-maven-plugin
ManifestFirst Development is used since Eclipse PDE does not support PomFirst
Developing an Eclipse plug-in without PDE support

Include the Maven Tycho plug-in in your pom.xml file.

 <plugin>
               <groupId>org.eclipse.tycho</groupId>
               <artifactId>tycho-maven-plugin</artifactId>
               <version>0.23.0</version>
               <extensions>true</extensions>
           </plugin>

Include the target platform configuration as well, as shown below.

 <plugin>
               <groupId>org.eclipse.tycho</groupId>
               <artifactId>target-platform-configuration</artifactId>
               <version>0.23.0</version>
               <configuration>
                   <resolver>p2</resolver>
                   <environments>
                       <environment>
                           <os>linux</os>
                           <ws>gtk</ws>
                           <arch>x86</arch>
                       </environment>
                       <environment>
                           <os>linux</os>
                           <ws>gtk</ws>
                           <arch>x86_64</arch>
                       </environment>
                       <environment>
                           <os>win32</os>
                           <ws>win32</ws>
                           <arch>x86</arch>
                       </environment>
                       <environment>
                           <os>win32</os>
                           <ws>win32</ws>
                           <arch>x86_64</arch>
                       </environment>
                       <environment>
                           <os>macosx</os>
                           <ws>cocoa</ws>
                           <arch>x86</arch>
                       </environment>
                       <environment>
                           <os>macosx</os>
                           <ws>cocoa</ws>
                           <arch>x86_64</arch>
                       </environment>
                   </environments>
               </configuration>
           </plugin>

Constraints when using Tycho

The artifactid in the pom.xml must be equal to the bundle ID in the META-INF/manifest.mf file.

The version in the pom.xml must be equal to the bundle version in the META-INF/manifest.mf file.

Resolving dependencies with Tycho

Instead of explicitly defining dependencies in your pom.xml file, define all dependencies in the META-INF/manifest.mf file (by defining the imported packages that are exported by other plug-ins/bundles).

P2 repositories that contain the dependent bundles (that export those imported packages), should be configured as repositories in the pom.xml file (with the layout set as p2). For example, if you are using bundles provided by Developer Studio Kernel, you should add the Kernel p2 as a repository as shown below.

<repository>
       <id>DevS-Deps-p2-Repository</id>           
       <url>http://builder1.us1.wso2.org/~developerstudio/developer-studio-kernel/4.0.0/p2/</url>
       <layout>p2</layout>
</repository>

In addition, you need to add the Eclipse Luna p2 repo,

<repository>
           <id>Eclipse-p2-repo</id>
           <url>http://download.eclipse.org/releases/luna/</url>
           <layout>p2</layout>
</repository>

In each p2 repo, you need to include a category.xml file, which selects features for the p2 repository and specifies how to categorize them in the p2 installation dialog box. This file should be a single file per p2 repository. For example,

<?xml version="1.0" encoding="UTF-8"?>
<site>
  <feature id="feature.id" version="1.4.100.v2009"/>
  <bundle id="bundle.id" version="1.3.1.v2013"/>
  <iu id="unit.id"/>
  <iu>
    <query> 
      <expression type="match">
        <![CDATA[
          id == $0
        ]]>
      </expression>
      <param>another.unit.id</param>
    </query>
  </iu>

  <feature id="feature.in.category">
     <category name="category.id"/>
  </feature>
  <category-def name="category.id" label="Category Label">
     <description>Details on the category</description>
  </category-def>

  <!-- example for a dynamic category -->
  <category-def name="javax" label="Bundles starting with javax."/>
  <iu>
     <category name="javax"/>
     <query><expression type="match">id ~= /javax.*/</expression></query>
  </iu>
</site>

You also need to have the feature.xml file in each and every feature you create to specify what plug-ins are included in this feature. For example, the API Manager feature's feature.xml file looks like the following,

<?xml version="1.0" encoding="UTF-8"?>
<feature
     id="org.wso2.developerstudio.eclipse.apim.feature"
     label="WSO2 API Manager Tooling Feature"
     version="4.0.0.qualifier"
     provider-name="%providerName">

  <description url="http://wso2.com">
     This feature will install plugins related WSO2 API Mangager Support.
  </description>

  <copyright url="%copyrightURL">
     %copyright
  </copyright>

  <license url="%licenseURL">
     %license
  </license>

  <requires>
     <import feature="org.wso2.developerstudio.eclipse.esb.feature" version="4.0.0" match="greaterOrEqual"/>
  </requires>

  <plugin
        id="org.wso2.developerstudio.eclipse.registry.apim.perspective"
        download-size="0"
        install-size="0"
        version="0.0.0"
        unpack="false"/>

</feature>

The copyright and the license are included for all features from a common location to avoid duplication, using a feature common properties file. You can refer the API-M feature folder structure from the API-M tooling git repository. For more details on feature.xml content, see Packaging and delivering Eclipse based products.

Using new third party dependencies

If you need to use a third party library, always try to get it from an existing p2 repository. In most cases, Eclipse P2 repository already provides common libraries such as Apache commons, gson, etc. However, if you cannot find such a p2 repo, we maintain our own dependencies p2 repo for those libraries here. You need to get your dependency converted into an OSGi bundle and get it published there. Contact the Developer Studio Kernel team who own this repository.

Tycko packaging types

According to the type of resource you want Tycho to build for you, you need to mention the packaging type. Tycho supports Eclipse plug-ins, Eclipse-test-plug-ins, features and p2 repos. By configuring the package type correctly in the pom.xml file, you can specify Tycho to build your project accordingly.

For example, the minimum pom.xml file for an Eclipse feature using Tycho should be as follows:

<project xmlns="http://maven.apache.org/POM/4.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
 <modelVersion>4.0.0</modelVersion>

 <groupId>some-group-id</groupId>
 <artifactId>feature id</artifactId>
 <version>feature version</version>
 <packaging>eclipse-feature</packaging>

</project>

For more information on how the minimum pom.xml file should look like for all project types, see Tycho/Packaging Types.