Support free tutorials:











vogella training Training Books



Eclipse Tycho for building Eclipse Plugins and RCP applications - Tutorial

Lars Vogel

Version 1.5

19.12.2013

Revision History
Revision 0.1 - 1.4 07.08.2011 - 19.12.2013 Lars
Vogel
bug fixes and enhancements

Eclipse Tycho

This tutorial describes the usage of Eclipse Tycho to build Eclipse plug-ins and Eclipse RCP applications

This tutorials is based on Eclipse 4.3 and Java 1.6.


Table of Contents

1. Build tools
2. Tycho
2.1. What is Tycho?
2.2. pom.xml configuration files
2.3. Source Encoding
2.4. Package attribute
2.5. Target Platform
2.6. Eclipse Maven Integration
2.7. Generating pom files via Tycho
2.8. Defining special build settings
3. Pre-requirements
4. Installation
4.1. Maven command line
4.2. m2eclipse plug-in installation
5. Tutorial: Building Eclipse components
5.1. Overview
5.2. Create master project for the build
5.3. Create projects to build
5.4. Create pom for plug-in project
5.5. Create pom for feature
5.6. Create pom for p2 update site
5.7. Create a JUnit test for the plugin
5.8. Building
6. Building Eclipse products
7. Automatic deployment
8. Support free vogella tutorials
8.1. Thank you
8.2. Questions and Discussion
9. Links and Literature
9.1. Source Code
9.2. Maven Tycho resources

1. Build tools

A buildtool is used to automate repetitive tasks. This can be, for example, compiling source code, running software tests and creating files and documentation for the software deployment.

Build tools typically run without a graphical user interface (headless) directly from the command line.

Popular build tools in the Java space are Apache Ant, Maven and Gradle.

2. Tycho

2.1. What is Tycho?

Eclipse Tycho is a set of Maven plug-ins which provides support for building Eclipse components.

Tycho supports the build process of Eclipse plug-ins, features, update sites (based on p2) and products.

Tycho uses the metadata of the Eclipse components in the MANIFEST.MF file as much as possible. This leads to relative small pom.xml configuration files.

The Tycho plug-ins are automatically installed into Maven based on the pom.xml configuration files you provide.

2.2. pom.xml configuration files

The configuration for Tycho build is stored in pom.xml files. To build Eclipse components with Tycho you typically create a master configuration file which includes the Tycho plug-ins and the definition of the build environment. Within this master configuration file you include all Eclipse components which should be built as modules.

This module definition in your master pom.xml file could for example look like the following.

<modules>
  <module>de.vogella.tycho.plugin</module>
  <module>de.vogella.tycho.plugin2</module>
  <module>de.vogella.tycho.feature</module>
</modules> 

A typical master pom.xml file looks like the following.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.vogella</groupId>
  <artifactId>parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>
  <modules>
    <module>../de.vogella.tycho.plugin</module>
    <module>../de.vogella.tycho.feature</module>
    <module>../de.vogella.tycho.p2updatesite</module>
    <module>../de.vogella.tycho.plugin.tests</module>
  </modules>

  <properties>
    <tycho.version>0.19.0</tycho.version>

    <kepler-repo.url>http://download.eclipse.org/releases/kepler</kepler-repo.url>
  </properties>

  <repositories>
    <repository>
      <id>kepler</id>
      <url>${kepler-repo.url}</url>
      <layout>p2</layout>
    </repository>

  </repositories>

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

      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>target-platform-configuration</artifactId>
        <configuration>
          <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_64</arch>
            </environment>
          </environments>
        </configuration>
      </plugin>
    </plugins>

  </build>

</project> 

Each module has again a pom.xml configuration file which defines attributes specifically to the corresponding Eclipse component, e.g. the package attribute. The pom.xml files of the modules refer to their parent pom.xml file.

2.3. Source Encoding

You can set the source code encoding via the project.build.sourceEncoding parameter.

<properties>
 <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties> 

2.4. Package attribute

The package attribute defines which Eclipse components should be created by Tycho.

Table 1. Package Attribute

Package Attribute Description
eclipse-plugin Used for Plug-ins
eclipse-feature Used for features
eclipse-repository Used for p2 update sites and Eclipse products

After setting up your pom.xml configuration files, you can build your Eclipse components with following commands.

# Switch to the directory 
# of you master build file
cd your_master_build_dir

# Alternatively use the following
mvn clean verify

# To get debug output use the -X flag
mvn clean verify -X 

Tip

It is not recommened to use the mvn clean install command, instead you should use mvn clean verify. If you would use the install option, the build result would be installed in your local Maven repository and this can lead to build problems.

2.5. Target Platform

The target platform is the set of artifacts from which Tycho resolves the project's dependencies. You can either use a target definition based on the Eclipse p2 update manager or on Target Definition files.

The following description uses p2 repositories, for a setup using Target Definition files please check the links at the end of this book.

2.6. Eclipse Maven Integration

Maven also provides a plug-in which integrates Maven into the Eclipse IDE. The installation and usage of this plug-in is not described as this book uses the Maven built from the command line.

2.7. Generating pom files via Tycho

Tycho allows to created default pom.xml configuration files. You can use the following command to generate default files. The -DgroupId allows you to specify the group ID for the pom files.

# Group ID is set to com.vogella.tycho.build 
mvn org.eclipse.tycho:tycho-pomgenerator-plugin:generate-poms \
  -DgroupId=com.vogella.tycho.build 

This will generate a pom for all modules below the current directory and a parent pom in the current directory. If you want to include Eclipse components which are not in the current directory you can point Tycho to these directories via the -DextraDirs parameter.

mvn org.eclipse.tycho:tycho-pomgenerator-plugin:generate-poms \
 -DgroupId=com.vogella.tycho.build -DextraDirs="../../another_plugin_dir 

You can also update existing pom files with the latest version number via the following command.

# update pom files
mvn org.eclipse.tycho:tycho-versions-plugin:update-pom 
  -Dtycho.mode=maven 

2.8. Defining special build settings

Maven and Tycho have pretty good default settings which fit the most realworld scenarios. But if this default values does not fit your needs, it is possible to configure single maven plugins via the pluginManagement tag. By defining settings with the pluginManagement, the plugins are actually not used, it is just configured. To use a plugin, you have to include it within the plugins tag.

As an example the following pom.xml shows how to use the current git commit timestamp as qualifier instead of the current system time stamp. This allows to build reproducible results with versioning depending on the sourcecode version. This onle works if the project is in a git repository.

<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/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>de.vogella.tycho.jgit.plugin</groupId>
  <artifactId>de.vogella.tycho.jgit.plugin</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <packaging>eclipse-plugin</packaging>

  <properties>
    <tycho.version>0.19.0</tycho.version>
    <tycho-extras.version>0.19.0</tycho-extras.version>
    <kepler-repo.url>http://download.eclipse.org/releases/kepler</kepler-repo.url>
  </properties>

  <repositories>
    <repository>
      <id>kepler</id>
      <url>${kepler-repo.url}</url>
      <layout>p2</layout>
    </repository>

  </repositories>

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

      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>target-platform-configuration</artifactId>
      </plugin>
    </plugins>
    <pluginManagement>
      <plugins>
        <plugin>
          <groupId>org.eclipse.tycho</groupId>
          <artifactId>tycho-packaging-plugin</artifactId>
          <version>${tycho.version}</version>
          <dependencies>
            <dependency>
              <groupId>org.eclipse.tycho.extras</groupId>
              <artifactId>tycho-buildtimestamp-jgit</artifactId>
              <version>${tycho-extras.version}</version>
            </dependency>
          </dependencies>
          <configuration>
            <timestampProvider>jgit</timestampProvider>
            <jgit.ignore>
              pom.xml
            </jgit.ignore>
            <jgit.dirtyWorkingTree>ignore</jgit.dirtyWorkingTree>
          </configuration>
        </plugin>
      </plugins>
    </pluginManagement>
  </build>

</project> 

3. Pre-requirements

The following assumes that you are familiar with Eclipse plug-in and RCP development, e.g. the creation of plug-ins, features and products. Check Eclipse Plug-in Tutorial and Eclipse RCP Tutorial. Also see Eclipse Feature Project to learn how to create feature projects.

4. Installation

4.1. Maven command line

The installation of Maven is described on the following website. You need to install Maven3.

http://maven.apache.org/download.html#Installation 

4.2. m2eclipse plug-in installation

You can also install the Maven Eclipse tooling. Install the m2eclipse plug-in into Eclipse via the following update site.

http://download.eclipse.org/technology/m2e/releases 

5. Tutorial: Building Eclipse components

5.1. Overview

The following description demonstrates how to build Eclipse plug-ins, features and how to create Eclipse p2 update sites with Maven Tycho.

This tutorial is a stand-alone description for building Eclipse plug-ins and features, e.g. all required Eclipse components are created in this tutorial.

5.2. Create master project for the build

Create a new project of type General called de.vogella.tycho.master.

Create the following pom.xml file in this project.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.vogella</groupId>
  <artifactId>parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>
  <modules>
    <module>../de.vogella.tycho.plugin</module>
    <module>../de.vogella.tycho.feature</module>
    <module>../de.vogella.tycho.p2updatesite</module>
    <module>../de.vogella.tycho.plugin.tests</module>
  </modules>

  <properties>
    <tycho.version>0.19.0</tycho.version>

    <kepler-repo.url>http://download.eclipse.org/releases/kepler</kepler-repo.url>
  </properties>

  <repositories>
    <repository>
      <id>kepler</id>
      <url>${kepler-repo.url}</url>
      <layout>p2</layout>
    </repository>

  </repositories>

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

      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>target-platform-configuration</artifactId>
        <configuration>
          <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_64</arch>
            </environment>
          </environments>
        </configuration>
      </plugin>
    </plugins>

  </build>

</project> 

5.3. Create projects to build

Create a new plug-in project called de.vogella.tycho.plugin.

Create a new feature project called de.vogella.tycho.feature which includes the de.vogella.tycho.plugin plug-in.

Create a new project of type General called de.vogella.tycho.p2updatesite. Select the main folder of this project and select FileNewOther...Plug-in DevelopmentCategory Definition. Create a new category and include your feature project.

The tests of the implementation belong into a separate plug-in. So create a new plug-in project called de.vogella.tycho.plugin.tests which requires org.junit;bundle-version="4.11.0" and de.vogella.tycho.plugin

5.4. Create pom for plug-in project

Create the pom.xml file for the de.vogella.tycho.plugin project.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <relativePath>../de.vogella.tycho.master/pom.xml</relativePath>
    <groupId>com.vogella</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>de.vogella.tycho.plugin</artifactId>
  <packaging>eclipse-plugin</packaging>
</project> 

5.5. Create pom for feature

Create the following pom.xml file for the de.vogella.tycho.feature project.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <relativePath>../de.vogella.tycho.master/pom.xml</relativePath>
    <groupId>com.vogella</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>de.vogella.tycho.feature</artifactId>
  <packaging>eclipse-feature</packaging>

</project> 

5.6. Create pom for p2 update site

Create the following pom.xml file for de.vogella.tycho.p2update project.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <relativePath>../de.vogella.tycho.master/pom.xml</relativePath>
    <groupId>com.vogella</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>de.vogella.tycho.p2updatesite</artifactId>
  <packaging>eclipse-repository</packaging>

</project> 

5.7. Create a JUnit test for the plugin

Create the following pom.xml file for de.vogella.tycho.plugin.test project.

<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/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <relativePath>../de.vogella.tycho.master/pom.xml</relativePath>
    <groupId>com.vogella</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>de.vogella.tycho.plugin.tests</artifactId>
  <packaging>eclipse-test-plugin</packaging>
</project> 

5.8. Building

Switch to the directory of your master plug-in and type the following commands to build your components.

# Switch to the directory 
# of you master build file
cd your_master_build_dir

# Alternatively use the following
mvn clean verify

# To get debug output use the -X flag
mvn clean verify -X 

6. Building Eclipse products

You can also use Tycho to build Eclipse based products.

For the purpose of a product build, you should create a separate project for your product configuration file. To build your product with Tycho you need to enter the ID on the product configuration file.

In this project you would create a pom.xml file which specifies the creation of a p2 update site for your product and the creation of a zip file.

For example the following shows such a pom.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <relativePath>../de.vogella.tycho.master/pom.xml</relativePath>
    <groupId>com.vogella</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>


  <artifactId>de.vogella.tycho.rcp.product</artifactId>
  <packaging>eclipse-repository</packaging>


  <build>
    <plugins>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-p2-repository-plugin</artifactId>
        <version>${tycho.version}</version>
        <configuration>
          <includeAllDependencies>true</includeAllDependencies>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-p2-director-plugin</artifactId>
        <version>${tycho.version}</version>
        <executions>
          <execution>
            <id>materialize-products</id>
            <goals>
              <goal>materialize-products</goal>
            </goals>
          </execution>
          <execution>
            <id>archive-products</id>
            <goals>
              <goal>archive-products</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project> 

To build a product you need to build your own plug-ins and features. This process is the same as described earlier. Also the master configuration file is the same.

The following example shows a master pom.xml. In this example your Eclipse RCP application consists out of one plug-in and one feature.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.vogella</groupId>
  <artifactId>parent</artifactId>
  <version>1.0.0-SNAPSHOT</version>
  <packaging>pom</packaging>
  <modules>
    <module>../de.vogella.tycho.rcp.application</module>
    <module>../de.vogella.tycho.rcp.feature</module>
    <module>../de.vogella.tycho.rcp.product</module>
  </modules>

  <properties>
    <tycho-version>0.19.0</tycho-version>
  </properties>

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

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

    </plugins>

  </build>

</project> 

To ensure that your product can be executed after the build, you have to set the start levels and the auto-start flag for the following plug-ins in your product configuration file on the Configuration tab,

org.eclipse.core.runtime Start-Level 2
org.eclipse.equinox.ds Start-Level  3
org.eclipse.equinox.event Start-Level 3 

7. Automatic deployment

You can use the Maven deployment artifact to deploy your artifacts, e.g. to an ftp server.

Add an entry for the user credentials to your local ~/m2/settings.xml file.

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <usePluginRegistry/>
  <offline/>
  <pluginGroups/>
  <servers>
    <server>
      <id>ftp-repository</id>
      <username>youruser</username>
      <password>yourpassword</password>
    </server>
  </servers>
  <mirrors/>
  <proxies/>
  <profiles/>
  <activeProfiles/>
</settings> 

You can then configure your pom.xml to use the deployment module of Maven.

<project>
  <distributionManagement>
    <repository>
      <id>ftp-repository</id>
      <url>ftp://repository.mycompany.com/repository</url>
    </repository>
  </distributionManagement>

  <build>
    <extensions>
      <!-- Enabling the use of FTP -->
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
         <artifactId>wagon-ftp</artifactId>
         <version>1.0-beta-6</version>
      </extension>
    </extensions>
  </build>
</project> 

The following command will now deploy your artifacts to your ftp site.

mvn deploy 

If you only want to upload your p2 update site, you can configure the org.apache.maven.wagon plug-in.

<?xml version="1.0" encoding="UTF-8"?>
<project>
  <modelVersion>4.0.0</modelVersion>

  <parent>
    <relativePath>../de.vogella.tycho.master/pom.xml</relativePath>
    <groupId>com.vogella</groupId>
    <artifactId>parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
  </parent>

  <artifactId>de.vogella.tycho.p2updatesite</artifactId>
  <packaging>eclipse-repository</packaging>

  <name>Tycho Test Build</name>

 <build>
  <extensions>
   <!-- Enabling the use of FTP -->
   <extension>
    <groupId>org.apache.maven.wagon</groupId>
    <artifactId>wagon-ftp</artifactId>
    <version>1.0-beta-6</version>
   </extension>
  </extensions>
 </build>

 <profiles>
  <!-- This profile is used to upload the repo -->
  <profile>
   <id>uploadRepo</id>
   <properties>
    <!-- Properties relative to the 
    distant host where to upload the repo -->
    <ftp.url>ftp://your.server.com</ftp.url>
    <ftp.toDir>/yourpath</ftp.toDir>
    <!-- Relative path to the repo being uploaded -->
    <repo.path>${project.build.directory}/repository/</repo.path>
   </properties>

   <build>
    <plugins>
     <!-- Upload the repo to the server -->
     <plugin>
      <groupId>org.codehaus.mojo</groupId>
      <artifactId>wagon-maven-plugin</artifactId>
      <version>1.0-beta-4</version>
      <executions>
       <execution>
        <id>upload-repo</id>
        <phase>install</phase>
        <goals>
         <goal>upload</goal>
        </goals>
        <configuration>
         <fromDir>${repo.path}</fromDir>
         <includes>**</includes>
         <toDir>${ftp.toDir}</toDir>
         <url>${ftp.url}</url>
         <serverId>p2Repo</serverId>
         <!-- Points to your settings.xml 
         where the connection settings are 
          stored as shown below -->
         <!-- <server> -->
         <!-- <id>p2Repo</id> -->
         <!-- <username>username</username> -->
         <!-- <password>password</password> -->
         <!-- </server> -->
        </configuration>
       </execution>
      </executions>
     </plugin>
    </plugins>
   </build>
  </profile>
 </profiles>

</project> 

You can now upload your p2 update site with the following command.

mvn install -P uploadRepo 

8. Support free vogella tutorials

Maintaining high quality free online tutorials is a lot of work. Please support free tutorials by donating or by reporting typos and factual errors.

8.1. Thank you

Please consider a contribution if this article helped you.

Flattr this

8.2. Questions and Discussion

If you find errors in this tutorial, please notify me (see the top of the page). Please note that due to the high volume of feedback I receive, I cannot answer questions to your implementation. Ensure you have read the vogella FAQ as I don't respond to questions already answered there.

9. Links and Literature

9.1. Source Code

Source Code of Examples

9.2. Maven Tycho resources

CBI article from Thanh Ha

Download the Tycho examples via

git clone git://git.eclipse.org/gitroot/tycho/org.eclipse.tycho-demo.git 

Tycho Book from the Tycho project

Minerva - Maven version of Athena

Tycho Reference Card

Tycho Target Platform

Maven deployment artifact