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.

8 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
  4. Hi Great tutorials..helped a lot
    I have a pluign which contains other plugins and feature projects.

    After Following your tutorial I am able to build pluign using tycho and I am getting deliverables in eclipsepluginupdateSite\target in zip format which is working fine for single version of eclipse.

    Now I am facing error how to configure tycho for to build multiple version of same plugin?

    In manual process I am following below steps:
    For example I want to create a plugin with version 4.8.800
    1. Delete eclipsepluignupdatesite features, pluigns, artifacts.jar and content.jar
    2. Copy previous versions features, plugins, artifacts.jar and content.jar in eclipsepluignupdatesite (e.g. previous version plugin is 4.6.612,4.7.711)
    3. Use export wizard for build plugins.
    4. Now In eclipsepluginupdatesite I found features, plugins, artifacts.jar and content.jar with contains plugin version 4.6.612,4.7.7.711 and also 4.8.800

    I copied whole eclipsepluginupdate contents under a host server url.
    When I use that url to install plugin It shows me three category 4.6,4.7,4.8
    Under each category I have plugin 4.6.3.612, 4.7.0.711, 4.8.0.800 and I can install any plugin.


    Using tycho I am able to build single plugin but I am not getting how to build plugin along with previous plugins using tycho.
    Please help me out

    Thanks in advance

    ReplyDelete