Tycho build 1: Building plug-ins

Tycho is a great build tool for all your RCP build needs. It is a plug-in to maven and helps you to set up a reproducible build process which can be run interactively from your IDE or in headless mode (eg. on a build server).

While there are already some tutorials out there (Mattias Holmqvist, Lars Vogel) how to integrate tycho, I could not find one that focuses on UI integration of maven. This article was heavily inspired by a great talk during EclipseCon by Jan Sievers and Tobias Oberlies.

I will set this up as a series of posts. We will start by building a single plug-in and end up with a whole application built with tycho.

During the tutorial I will use a plain installation of Eclipse for RCP and RAP Developers, Mars. No external programs are needed (so you don't need to install maven separately).

Tycho Tutorials

For a list of all tycho related tutorials see Tycho Tutorials Overview

Source code for this tutorial is available on github as a single zip archive, as a Team Project Set or you can browse the files online.

Preparations

Before we start using tycho I created a short sample project consisting of a small eclipse-like product along with an additional feature. The latter contains one plug-in that provides a custom toolbar entry and an (almost empty) view.

 You can grab the initial sources from github as a single zip archive, as a Team Project Set or you can browse the files online. 

Step 1: Install Tycho connector

Eclipse for RCP and RAP Developers already comes with m2e, the maven integration tools of eclipse. Maven itself needs to be extended with tycho to allow to build plug-ins and other RCP like things.

Go to Preferences/Maven/Discovery and click on Open Catalog. Find and select the Tycho Configurator.

Install it and restart eclipse.

Step 2: Build a simple plug-in project

We will start by building com.codeandme.tycho.plugin. Right click on the project and select Configure/Convert to Maven Project.

The wizard asks for a Group Id. Use a name that represents the component you want to build. Think of a component as a thing to assemble like my_product or JDT, PDE, ... you get the point. All projects that belong together will get the same Group Id.

Leave the Artifact Id to the name of your project. Actually it should match the Bundle-SymbolicName found in MANIFEST.MF.

Version should be set accordingly to Bundle-Version from the manifest. Later we will see how to keep those consistent. SNAPSHOT in maven is similar to qualifier in you plug-in version.

Finally Packaging tells maven what type of build instructions to use. Set it to eclipse-plugin.

Maven creates a pom.xml for you which we immediately replace with this one:

<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>tycho_example</groupId>
 <artifactId>com.codeandme.tycho.plugin</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>eclipse-plugin</packaging>

 <properties>
  <tycho.version>0.23.0</tycho.version>
 </properties>

 <repositories>
  <!-- add Mars repository to resolve dependencies -->
  <repository>
   <id>Mars</id>
   <layout>p2</layout>
   <url>http://download.eclipse.org/releases/mars/</url>
  </repository>
 </repositories>

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

Lines 9-11 add a property for the tycho version to be used. For future tycho versions you will need to upgrade this.
Lines 13-20 add the Mars p2 repository for resolving dependencies during build time.
The build section (lines 22-32) tells maven to use the tycho plug-in for the build process.

Now you will see one error in your Problems View:

We will face this error each time we convert a project to maven. To get rid of it select it in the Problems View and use the Quick Fix (from the context menu or by pressing Ctrl-1).You might face other error markers too, that indicate that some maven plugins cannot be found. They should valish after the first build, which will fetch all the requirements.

Time to build our bundle: Right click on the project and select Run As/Maven build... Under Goals enter clean install. Goals are related to the maven lifecycle. See it as something similar to make targets if you are used to that. Basically we tell maven to delete previous build artifacts, to build our plug-in and to install build results.

The first run will take some time as dependencies need to be downloaded from the Mars p2 site and from the maven central. At the end you should see something like this in your Console View:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 18.128s
[INFO] Finished at: 2015-07-30T14:11:20+02:00
[INFO] Final Memory: 58M/139M
[INFO] ------------------------------------------------------------------------

Now check your project to find a new folder called target. It contains your build artifacts along with intermediate build files. Tycho will not refresh your workspace, so you have to do that manually to see the content of your target folder. If you want eclipse to do this automatically then open the run target you created before, switch to the Refresh tab and refresh The project containing the selected resource.

Additionally tycho changed your .classpath file to write output to target/classes instead of the default bin folder.

Congratulations, you've just built your first plug-in with tycho.

Optional: Proxy support

If you need to access the internet via a proxy, check out tutorial 2 first to see how to set the proxy server in maven.