Sunday, January 6, 2013

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, Juno SR1. No external programs are needed (so you don't need to install maven separately).

Tycho Tutorials

1 Building plug-ins
2 Global maven settings
3 Global build project
4 Building features
5 Building p2 update sites
6 Building products
7 Plug-in unit tests
8 Using target platforms
9 Updating version numbers

Source code for this tutorial is available on googlecode as a single zip archive, as a Team Project Set or you can checkout the SVN projects directly.

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 googlecode as a single zip file.

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.example.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.example.tycho.plugin</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>eclipse-plugin</packaging>

 <properties>
  <tycho-version>0.16.0</tycho-version>
 </properties>

 <repositories>
  <!-- add Juno repository to resolve dependencies -->
  <repository>
   <id>Juno</id>
   <layout>p2</layout>
   <url>http://download.eclipse.org/releases/juno/</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 Juno 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).

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 Juno p2 site. 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: Tue Nov 27 15:08:40 CET 2012
[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.

6 comments:

  1. After installing eclipe-rcp and the tycho configurator I imported the projects. Then I select in the context menu "Configure - Convert to Maven project".

    Under "packaging" there are "jar", "war" and "pom". There isn't the selection "eclipse-plugin"?

    ReplyDelete
    Replies
    1. You are right. M2e will not list those tycho packaging types. You have to type them instead of selecting...

      Delete
    2. If I enter them explicitly, I got an error message, which I don't know how to fix

      Delete
    3. Please be a bit more specific. Which error message did you get after which step of the tutorial?

      Delete
  2. Hej! (I wrote the question)

    Thanks for your great tutorial! I have managed to migrate our project!

    ReplyDelete
  3. This tutorial helped me a lot with Tycho. Many thanks!

    ReplyDelete