eclipse-tycho

Tutorial how to add Tycho to an existing Eclipse Plug-in feature...

Table of content

• Adding Tycho
• Main Pointers to the essential files before the explanation
• Step by step instructions
  • Create Parent POM
  • Add a Target Definition as a Maven Module
  • Define the Eclipse repository for the build
  • Add POMs for the existing Feature and UI Plug-Ins
  • Launch Configurations
  • Adding Unit TEsts
• Setting up your own project
  • Create a Plug-in
  • Create a Feature
  • Export as p2 repository
  • Share into a GIT repository

Adding Tycho

Below I describe in Setting up your own Project the prerequisites of these instruction. I start with a basic Eclipse feature project and a basic Eclipse plug-in project.

This tutorial is based on the following information:

• Tycho Reference Card
• http://www.vogella.com/tutorials/EclipseTycho/article.html
• https://github.com/vogellacompany/tycho-example

Main Pointers to the essential files before the explanation

As a kind of management summary...

• Parent POM
• Target POM
• Target Definition
• P2 Repository POM
• P2 Repository Manifest
• Feature POM
• Plug-in POM
• Unittest POM

Step by step instructions

Create Parent POM

The spirit and purpose of the parent POM is to make the definition of the children easier. So most of the basic definition is placed in this file. Define a groupId and an artifactId for your project and choose as version 1.0.0-SNAPSHOT (since all plugins are automatically created with version 1.0.0.qualifier.

<groupId>org.example.eclipse.tycho</groupId>
<version>1.0.0-SNAPSHOT</version>
<artifactId>org.example.eclipse.tycho.parent</artifactId>
<packaging>POM</packaging>

Choose as properties the current tycho version, the java version and the encoding of the files in your workspace:

<properties>
	<tycho-version>1.0.0</tycho-version>
	<project.build.sourceEncoding>windows-1252</project.build.sourceEncoding>
	<Maven.compiler.source>1.8</Maven.compiler.source>
	<Maven.compiler.target>1.8</Maven.compiler.target>
</properties>

At this time leave the modules section empty.

Now define the plugins that are needed for the build:

• Compile application sources with eclipse plugin dependencies: org.eclipse.tycho / tycho-Maven-plugin / ${tycho-version}
• Perform unit tests: org.eclipse.tycho / tycho-surefire-plugin / ${tycho-version}
• Create a JAR-package containing all the source files of a osgi project. org.eclipse.tycho / tycho-source-plugin / ${tycho-version}
• Generate a source feature for projects of packaging type eclipse-feature org.eclipse.tycho / tycho-source-feature-plugin / ${tycho-version}
• Generate p2 metadata for the repository org.eclipse.tycho / tycho-p2-plugin / ${tycho-version}
• Specify which environments your software should be built for org.eclipse.tycho / target-platform-configuration / ${tycho-version}

Unfortunately Eclipse partially does not know what to do with the plugins and messages like Plugin execution not covered by lifecycle configuration: org.apache.Maven.plugins:Maven-clean-plugin:2.5:clean (execution: default-clean-1, phase: initialize) will pop up in your POM editor. To solve this long-standing issue the plugin org.eclipse.m2e / lifecycle-mapping was created. This plugin basically sets the ignore action for the plugin-goal-combination that Eclipse should ignore in its workspace.

You can find the complete POM in the github repository: parent pom.xml

Add a Target Definition as a Maven Module

Having set the basic information how to compile the eclipse feature the target has to be defined. Create a new module to hold the target definition to be used by the build. Be sure to set eclipse-target-definition as the packaging of the POM.

Now create a target definition for the build, using the desired Eclipse Platform version:

The editor for this does not create a target definition I like. So use an text to create the content:

<?xml version="1.0" encoding="UTF-8"?>
<?pde version="3.8"?>
<target name="org.example.eclipse.tycho.target" sequenceNumber="18">
<locations>
<location includeAllPlatforms="false" includeConfigurePhase="true" includeMode="planner" includeSource="true" type="InstallableUnit">
<unit id="org.eclipse.platform.feature.group" version="0.0.0"/>
<unit id="org.eclipse.jdt.feature.group" version="0.0.0"/>
<repository location="http://download.eclipse.org/releases/oxygen/201712201001"/>
</location>
</locations>
<environment>
<os>win32</os>
<ws>win32</ws>
<arch>x86_64</arch>
</environment>
</target>

This refers to the Eclipse Oxygen.2 release repository and defines dependencies to

• org.eclipse.platform.feature.group
• org.eclipse.jdt.feature.group

It defines the desired runtime environment for this target as well.

Define the Eclipse repository for the build

We are still not there. Now we need to define the p2 repository for the build output and create a category manifest. Make sure to choose eclipse-repository as the packaging of the POM.

Unfortunately I found no way to create the desired output using the manifest editor. So I chose the XML editor instead:

<?xml version="1.0" encoding="UTF-8"?>
<site>
   <feature id="org.example.eclipse.tycho.feature" version="0.0.0">
      <category name="main"/>
   </feature>
   <feature id="org.example.eclipse.tycho.feature.source" version="0.0.0">
      <category name="main.source"/>
   </feature>
   <category-def name="main" label="Eclipse Tycho Demo"/>
   <category-def name="main.source" label="Eclipse Tycho Demo (Sources)"/>
</site>

Since the source feature is created by the build it can not be referenced by the editor.

Add POMs for the existing Feature and UI Plug-Ins

Use Configure --> Convert to Maven Project to convert the feature and plug-in projects. Then add the following pom.xml files to the projects:

Main content of feature/pom.xml

<parent>
	<groupId>org.example.eclipse.tycho</groupId>
	<artifactId>org.example.eclipse.tycho.parent</artifactId>
	<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>org.example.eclipse.tycho.feature</artifactId>
<packaging>eclipse-feature</packaging>

Main content of plugin/pom.xml

<parent>
	<groupId>org.example.eclipse.tycho</groupId>
	<artifactId>org.example.eclipse.tycho.parent</artifactId>
	<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>org.example.eclipse.tycho.ui</artifactId>
<packaging>eclipse-plugin</packaging>

As you can see there is just the reference to the parent POM, the artifactId, and the special eclipse packaging to set.

Launch Configurations

I provided the following Eclipse Launch configurations:

• mvn clean cleans up the Maven target directories
• mvn clean verify creates a p2 repository in the target folder of repository project (package is not enough since tycho-surefire-plugin runs in the Maven integration-test life cycle phase)
• mvn set-version is used to set the next version of the plugins whenever it needs a new version
• Launch Runtime Eclipse starts the plugins in a test workspace

Adding Unit Tests

The next step is to create a new plug-in for unit tests. The standard naming convention to suffix the plugin name with .tests.

At the current time there seems to be no easy way to add this project easily to the GIT project. I use the following steps:

• Delete the plug-in project (do not delete the project contents)
• Move the project into the GIT repository (using some sort of file manager)
• Use EGit Import Projects to import the deleted project again (but now automatically shared in the GIT repository.
• Add the plug-in as module to the parent POM
• Convert the new plug-in to a Maven Project

Create a pom.xml in the tests project with the following details. eclipse-test-plugin as packaging defines the plug-in as a unit test plug-in.

<parent>
	<groupId>org.example.eclipse.tycho</groupId>
	<artifactId>org.example.eclipse.tycho.parent</artifactId>
	<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>org.example.eclipse.tycho.tests</artifactId>
<packaging>eclipse-test-plugin</packaging>

Now

Setting up your own project

I used Eclipse Oxygen 2 to create the project:

Create a Plug-in

The following wizard creates a simple plug-in...

Create a Feature

Include the plug-in in the feature...

Export as p2 repository

Basically Eclipse provides everything to create a p2 repository

This yields a folder structure like:

Share into a GIT repository

Now you can share the plug-ins into an existing GIT repository with the standard EGit share command. So far so good.

Now I prepare the next step to add the Maven POMs: I transform the root of the GIT repository to an Eclipse project. To make it importable I add a .project file with the following content. This creates a Maven parent project, adding the Maven2 builder and nature. We do not need it yet but this gives a nice starting point for adding the Maven Tycho build in the next step.

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name>org.example.eclipse.tycho.parent</name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
		<buildCommand>
			<name>org.eclipse.m2e.core.Maven2Builder</name>
			<arguments>
			</arguments>
		</buildCommand>
	</buildSpec>
	<natures>
		<nature>org.eclipse.m2e.core.Maven2Nature</nature>
	</natures>
</projectDescription>