NOW Hiring

Quick links

This tutorial describes the usage of Eclipse Tycho to build Eclipse plug-ins and Eclipse RCP applications. It uses Tycho is version 0.25.0.

1. Pre-requirements for this tutorial

This tutorial assumes that you are familiar with Eclipse plug-ins and RCP development. Check Eclipse Plug-in Tutorial and Eclipse RCP Tutorial to learn about it. Also, see Eclipse Feature Project to learn how to create feature projects.

For a description how to install and use Maven on the command line see Apache Maven tutorial.

2. Using Maven Tycho to build Eclipse components

2.1. What is Tycho?

Tycho is a set of Maven plug-ins for building Eclipse components via the Maven build system. Tycho supports the build process of Eclipse plug-ins, OSGi bundles, Eclipse features and update sites (based on p2) and products. Combined with a continuous integration server, e.g., a Jenkins instance, Tycho allows a continuous integration build. Tycho uses the Eclipse components metadata as much as possible. For example, Tycho determines the dependencies of a plug-in via the MANIFEST.MF file of the plug-in.

The main Tycho functionality is provided by the tycho-maven-plugin plug-in. This is a plug-in for Maven which supports building Eclipse components. It also enables Maven to understand package types such as eclipse-plugin, eclipse-feature and eclipse-repository.

If you add this plug-in to your Maven build file, the Maven build system downloads Tycho and uses it for building Eclipse components.

2.2. Configuring the pom files for a Tycho build

A Tycho build is configured via the standard Maven configuration files typically called pom.xml or pom files.

For a Tycho build, you typically have one pom file for the main configuration (configuration pom) and another one which includes the Eclipse components (modules) relevant for the build (main pom).

Every Eclipse component can have its individual pom file but Tycho allows also to generate default pom files based on the existing metadata of the compoments. This is based on the Maven polyglot functionality introduced with Maven 3.3.1. If the generated defaults, are not sufficient for an Eclipse component you can always define a specialized pom file for the component.

2.3. Enable the generation of default pom files for Eclipse components

To enable the automatic determination of build information for your Eclipse components, add a .mvn/extensions.xml descriptor to the root of your directory. This requires at least Apache Maven 3.3 and Maven Tycho 0.24.0.

The contents of the .mvn/extensions.xml must look like this:

<extensions>
  <extension>
    <groupId>org.eclipse.tycho.extras</groupId>
    <artifactId>tycho-pomless</artifactId>
    <version>0.25.0</version>
  </extension>
</extensions>

The following rules are used for the automatic pom generation. First of all .qualifier from the Eclipse components is automatically mapped to -SNAPSHOT for the Maven build.

Table 1. Table Pom Properties Mapping
Property Mapping

packaging,

eclipse-plugin if MANIFEST.MF is found

eclipse-feature if feature.xml is found

eclipse-test-plugin if Bundle-SymbolicName ends with .tests

groupId

same as in the parent pom

arifactId

eclipse-plugin: Bundle-SymbolicName from MANIFEST.MF

eclipse-feature: feature id from feature.xml

version

Bundle-Version from MANIFEST.MF or

Feature version from feature.xml

2.4. Defining a specialized pom file for an Eclipse component

If you define a pom file for an Eclipse component, you need to specify the packaging attribute in the pom file. This attribute defines what kind of Eclipse component you are building. For example, a plug-in must set this attribute to eclipse-plugin.

Table 2. Table Package attributes for Eclipse components
Package Attribute Description

eclipse-plugin

Used for plug-ins

eclipse-test-plugin

Used for test plug-ins or fragments

eclipse-feature

Used for features

eclipse-repository

Used for p2 update sites and Eclipse products

eclipse-target-definition

Target definition used for the Tycho build

In addition to packaging attribute, the pom of an Eclipse component must also specify the name and the version of the component. The artifact ID and version in the pom file must match the Bundle-Symbolic-Name and the Bundle-Version from the MANIFEST.MF file. Eclipse components typical use qualifier as a suffix in the Bundle-Version to indicate that this should be replaced by the build system with a build qualifier. Maven uses "SNAPSHOT" for this, but Tycho maps these values correctly. Each module has again a pom.xml configuration file which defines attributes specifically to the corresponding Eclipse component, e.g., the package attribute.

It must also contain a link to the main or the configuration pom so that the build can determine the configuration.

The following listing contains an example pom file for a plug-in.

<project>
    <modelVersion>4.0.0</modelVersion>

    <!-- Link to the parent pom -->
    <parent>
        <artifactId>com.example.todo.build.parent</artifactId>
        <groupId>com.example.e4.rcp</groupId>
        <version>0.1.0-SNAPSHOT</version>
        <relativePath>../com.example.todo.build.parent</relativePath>
    </parent>

    <groupId>com.example.e4.rcp</groupId>
    <artifactId>com.example.e4.bundleresourceloader</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>eclipse-plugin</packaging>
</project>

2.5. Good practice for Eclipse components organization

To have some separation of the plug-ins a good practice is to have separate folders on the file system for them.

Tycho project setup

In a Tycho build it is good practice to create a configuration pom file. This file includes the Tycho plug-ins and the definition of the build environment. This pom file describes the general configuration. The folder which contains this build file is typically releng for Release Engineering.

In addition you create an aggregator build file which lists all Eclipse components which should be built as modules. The aggregator includes the configuration pom file as parent.

And the pom files in the different Eclipse projects contain primary the nature of the component (feature, plug-in, product, update site) and the version number from the MANIFEST.MF.

2.6. Starting the build

After setting up your pom configuration files, you can build your Eclipse components with the mvn clean verify command, or the mvn clean install command. It is recommended to use the mvn clean verify command. If the mvn clean install command is used, it would result in a build being installed in your local Maven repository and this can lead to build problems.

# run this inside the directory of your build
mvn clean verify

3. Defining the repository to find Eclipse dependencies for the build

3.1. Defining build dependencies

You need to define where Tycho can find the dependencies of your Eclipse components. By default, all components included in the build are available to resolve dependencies. For the remaining dependencies, you must configure Tycho where to search for them. This can be defined via a p2 repository or via a target platform definition.

3.2. Using p2 update sites for dependencies resolution

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

Alternative to p2 update sites you can also use a target definition file.

3.3. Using target definition file for dependencies resolution

Tycho uses a target platform to find dependencies. If you specify a p2 update site as target, the whole content of all defined p2 repositories becomes part of the target platform. If a target definition is used in the project for development, the build should also use this instead of using a whole repository.

Tycho only supports Software Sites as locations. The Directory Installation and Feature entries are not supported by Tycho and are ignored by the build process.

The target editor picks always the exact version of the plug-in from the update site. In case you building against dynamically changing p2 repositories, you can specify that the version is not important. Use in this case "0.0.0" as version qualifier. This change needs to be done, via a test editor, as the target editor does not support this. Tycho will select a version from the p2 update site, if several versions are available one of them is picked. == Executing plug-in unit tests with Tycho

3.4. Using the Tycho Surfire plug-in for execution plug-in tests

In Eclipse it is common practice to have a separate test plug-in or fragment project for your tests.

Tycho uses the eclipse-test-plugin packaging type for these projects. The test execution is done via the Tycho Surefire plug-in which is aware of plug-in dependencies.

<project>
        <modelVersion>4.0.0</modelVersion>

        <!--parent pom...  -->

        <artifactId>com.vogella.tycho.rcp.tests</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <packaging>eclipse-test-plugin</packaging>
</project>

Tycho builds test plug-ins similar as regular Eclipse plugins. The execution of the the tests happens in the integration-text life cycle phase of Maven. The runtime behavior of the Maven Tycho Surefire plug-in is a little different to the Maven Surefire plug-in. Tycho Surefire tests run in the integration-test phase while regular Maven Surefire tests run in the test phase. The integration-test phase occurs between the package and install phases.

The Tycho Surefire plug-in supports the execution of non-UI based and UI-based tests. If you run UI tests, you have to enabled that explicitly via the useUIHarness parameter.

<project>
        <modelVersion>4.0.0</modelVersion>

        <!--parent pom... -->

        <artifactId>com.vogella.tycho.rcp.tests</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <packaging>eclipse-test-plugin</packaging>

        <build>
                <plugins>
                 <plugin>
                        <groupId>org.eclipse.tycho</groupId>
                        <artifactId>tycho-surefire-plugin</artifactId>
                        <version>${tycho.version}</version>
                        <configuration>
                                <useUIHarness>true</useUIHarness>
                        </configuration>
                 </plugin>
                </plugins>
        </build>

</project>

The tests are executed in a test runtime (based on OSGi), using the dependencies defined in the MANIFEST.MF file of the test plug-in. You can also include more dependencies to features ("eclipse-feature"), plug-ins /fragments ("eclipse-plugin") or installable units ("p2-installable-unit"). If you define a dependency you include also their transitive dependencies, to the test runtime.

<project>
 <modelVersion>4.0.0</modelVersion>

 <!--parent pom... -->

 <artifactId>com.vogella.tycho.rcp.tests</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>eclipse-test-plugin</packaging>

 <build>
  <plugins>
   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-surefire-plugin</artifactId>
    <version>${tycho.version}</version>
    <configuration>
     <useUIHarness>true</useUIHarness>
     <dependencies>
      <dependency>
       <type>eclipse-feature</type>
       <artifactId>com.vogelal.feature1</artifactId>
       <!-- This is the minimum required version -->
       <version>1.0.0</version>
      </dependency>
     </dependencies>
    </configuration>
   </plugin>
  </plugins>
 </build>


</project>

3.5. Test selection

Similar to the Maven Surfire plug-in, Tycho Surfile selects, by default, all test classes matching the /Test*.java, /Test.java and */*TestCase.java for the test run.

This selection can be configured via the includes parameter.

<project>
        <modelVersion>4.0.0</modelVersion>

        <!--parent pom... -->

        <artifactId>com.vogella.tycho.rcp.tests</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <packaging>eclipse-test-plugin</packaging>

        <!-- Define to include all classes in the test run -->
        <build>
         <plugins>
          <plugin>
                <groupId>org.eclipse.tycho</groupId>
                <artifactId>tycho-surefire-plugin</artifactId>
                <version>${tycho.version}</version>
                 <configuration>
                  <includes>
                        <include>**/*.class</include>
              </includes>
                 </configuration>
           </plugin>
         </plugins>
        </build>
</project>

You can also specify a specific test or test suite to be executed.

This requires setting the TestSuite to the Bundle-Symbolic-Name of the plug-in and the testClass parameter to the fully qualified class.

<!-- snippet -->
<build>
 <plugins>
  <plugin>
          <groupId>org.eclipse.tycho</groupId>
           <artifactId>tycho-surefire-plugin</artifactId>
           <version>${tycho.version}</version>
           <configuration>
              <testSuite>org.eclipse.e4.ui.tests.css.swt</testSuite>
              <testClass>org.eclipse.e4.ui.tests.css.swt.CssSwtTestSuite</testClass>
           </configuration>
    </plugin>
 </plugins>
</build>

3.6. Using the correct JRE for the test execution

The JDT compiler can be configured to use the compiler source/target level according to MANIFEST.MF settings. So it is possible to compile a JavaSE-1.8 bundle using JDK 7, even if I started the build process with a Java 7 JVM.

This is not true for running the tests. The tests are running with the build JVM by default. So only because a Java 8 plug-in compiles, this does not mean that the correct JVM is used. If you test bundle requires for example Java 8, you must start the build process via a Java 8 JVM.

4. Exercise: Configure Tycho build

4.1. Target of this exercise

In this exercise you define the meta data to use pomless builds with Tycho. You also create the directory structure and the Eclipse projects to contain the main and configuration pom.

Displaying hierarchical projects

The Project Explorer view allows to see hierarchical projects. See screenshot for the required setting.

Project Explorer - hierarchical view

4.2. Create a new folder and create a root project in it

Select or create a new directory for this tutorial. In this directory, create a new project called com.vogella.tycho via the File ▸ New ▸ Other…​ ▸ General ▸ Project menu entry.

Create new project of type general
Create new project of type general - Part 2

This root project is supposed to contain all Eclipse components and the main pom file.

4.3. Enable pomless Tycho build

Create in the main directory (in the com.vogella.tycho project) a .mvn/extensions.xml descriptor. The content of the .mvn/extensions.xml must look like the following to enable pomless builds.

<extensions>
  <extension>
    <groupId>org.eclipse.tycho.extras</groupId>
    <artifactId>tycho-pomless</artifactId>
    <version>0.25.0</version>
  </extension>
</extensions>

4.4. Create pom for the build configuration

Create a new folder called releng in the main directory. In this folder create a new project of type General called com.vogella.tycho.configuration.

Create new project for the Tycho configuration

Create the following pom.xml file in this project.

<project>
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.vogella.tycho</groupId>
 <artifactId>com.vogella.tycho.configuration</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>pom</packaging>

 <properties>
  <tycho.version>0.25.0</tycho.version>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <mars-repo.url>http://download.eclipse.org/releases/mars</mars-repo.url>
 </properties>

 <repositories>
  <repository>
   <id>mars</id>
   <url>${mars-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>
    <version>${tycho.version}</version>
    <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>

4.5. Create pom in the root project

Create the following pom.xml file in the root project of your build.

<project>
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.vogella.tycho</groupId>
 <artifactId>com.vogella.tycho.root</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>pom</packaging>
 <parent>
   <groupId>com.vogella.tycho</groupId>
   <artifactId>com.vogella.tycho.configuration</artifactId>
   <version>1.0.0-SNAPSHOT</version>
  <relativePath>./releng/com.vogella.tycho.configuration</relativePath>
 </parent>

 <modules>
 </modules>
</project>

4.6. Validate build setup

The created directory structure should look like the following.

Directory after first build setup

Run the build via mvn clean verify, this build should be successful. No build artifact is created. == Exercise: Tycho build for plug-ins

4.7. Target of this exercise

The following exercise demonstrates how to build Eclipse plug-ins with Maven Tycho.

4.8. Creating a folder for your plug-ins

Create a new folder called bundles in the root project. This folder will contain your Eclipse plug-ins (OSGi bundles).

4.9. Creating a plug-in to build

In the bundles folder create a new plug-in project called com.vogella.tycho.plugin1.

Plug-in creation for Tycho

This plug-in does not require a pom file, the defaults from pomless are fine for this project.

4.10. Add pom for bundles directory

Create the following pom in the bundles directory.

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.bundles</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <parent>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.root</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <modules>
        <module>com.vogella.tycho.plugin1</module>
    </modules>
</project>

4.11. Add bundle to root pom

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.root</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <parent>
            <groupId>com.vogella.tycho</groupId>
            <artifactId>com.vogella.tycho.configuration</artifactId>
            <version>1.0.0-SNAPSHOT</version>
        <relativePath>./releng/com.vogella.tycho.configuration</relativePath>
    </parent>

    <modules>
        <module>bundles</module>
    </modules>
</project>

4.12. Run the build and validate the result

To run the build on the command line from your root directory via mvn clean verify. In your console you should see the BUILD SUCCESS statement.

Press F5 on your project in the Eclipse IDE to refresh it. You find a new folder called target in your project which contains the JAR file for your plug-in. The created JAR file still has the SNAPSHOT suffix. This suffix is replaced with the build time stamp once you build a product or an update site with the eclipse-repository packaging type.

Build result for the plug-in

You can also run the build from the bundles directory or the directory of the plug-in. This build should also run successfully.

5. Exercise: Tycho build for Eclipse features

5.1. Target of this exercise

The following description demonstrates how to build Eclipse features with Maven Tycho. It is based on [exercisetychoplugin].

5.2. Create features directory

Create a new directory called features in your main directory.

5.3. Create feature to build

Create a new feature project called com.vogella.tycho.feature in the features folder.

Feature creation for Tycho

Add the com.vogella.tycho.plugin1 plug-in to the feature.

Add plug-in to feature

5.4. Create pom for feature folder

Create the following pom in the features directory.

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.features</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <parent>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.root</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <modules>
        <module>com.vogella.tycho.feature</module>
    </modules>
</project>

The com.vogella.tycho.feature feature does not require an separate pom file, as we can use the generated defaults.

5.5. Add feature to root pom

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.root</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>
    <parent>
            <groupId>com.vogella.tycho</groupId>
            <artifactId>com.vogella.tycho.configuration</artifactId>
            <version>1.0.0-SNAPSHOT</version>
        <relativePath>./releng/com.vogella.tycho.configuration</relativePath>
    </parent>

    <modules>
        <module>bundles</module>
        <module>features</module> (1)
    </modules>
</project>
1 Adds the features pom to the build

5.6. Run the build

Run the build from the main directory. This should work fine.

[INFO] Reactor Summary:
[INFO]
[INFO] com.vogella.tycho.root ............................. SUCCESS [  0.055 s]
[INFO] com.vogella.tycho.bundles .......................... SUCCESS [  0.002 s]
[INFO] com.vogella.tycho.plugin1 .......................... SUCCESS [  0.518 s]
[INFO] com.vogella.tycho.features ......................... SUCCESS [  0.002 s]
[INFO] com.vogella.tycho.feature .......................... SUCCESS [  0.118 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Building the feature (from the features directory) will not work, as this requires com.vogella.tycho.plugin1 to be present in one of the repositories specified as dependency.

[ERROR] Missing requirement:
 com.vogella.tycho.feature.feature.group 1.0.0.qualifier
 requires 'com.vogella.tycho.plugin1 0.0.0' but it could not be found

If an independent build of the feature is required, you need to make the plug-in available via a repository. This can for example be done by building and installing the plug-in into the local Maven repository with the mvn clean install command.

Press F5 in the Eclipse IDE on your feature project to refresh it. You find a new target folder in your project which contains the JAR file for your feature. Also this JAR file still has the SNAPSHOT suffix. This suffix is replaced with the build time stamp once you build a product or an update site with the eclipse-repository packaging type.

6. Exercise: Tycho build for update sites

6.1. Target of this exercise

The following exercise demonstrates how to build Eclipse p2 update sites with Maven Tycho. It is based on the [exercisetychoplugin] and [exercisetychofeature] exercises.

6.2. Create a category definition file for the update site

In your releng folder, create a new project of type General. called com.vogella.tycho.update.

Project creation for update site

Right-click on this project and select File ▸ New ▸ Other…​ ▸ Plug-in Development ▸ Category Definition.

Press the New Category button and create a new category with the "tychoexample" ID and "Tycho example" name.

Adding a category

Press the Add Feature…​ button and include your feature project into the category.

Adding a feature to a category

6.3. Create pom file for the releng folder

Create the following pom file in the releng folder.

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.releng</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <parent>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.root</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <modules>
        <module>com.vogella.tycho.update</module>
    </modules>
</project>

6.4. Create pom for the update site

Create the following pom file for your update site project.

<project>
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.releng</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <artifactId>com.vogella.tycho.update</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>eclipse-repository</packaging>
</project>

6.5. Update the root pom

Add your new module to your root pom file.

<project>
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.vogella.tycho</groupId>
 <artifactId>com.vogella.tycho.root</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>pom</packaging>
 <parent>
   <groupId>com.vogella.tycho</groupId>
   <artifactId>com.vogella.tycho.configuration</artifactId>
   <version>1.0.0-SNAPSHOT</version>
  <relativePath>./releng/com.vogella.tycho.configuration</relativePath>
 </parent>

 <modules>
  <module>bundles</module>
  <module>features</module>
  <module>releng</module> (1)
 </modules>
</project>
1 Adds the releng pom to the aggregator build

6.6. Run aggregator build and validate the update site build result

Run the build from your main directory. It should complete sucessfully and build all your components including the update site.

Press F5 in the Eclipse IDE on your update site project to refresh it. You find a new target folder in your project which contains a repository folder. This folder contains the update site.

Build result

Validate that the JAR files in the "repository" have the SNAPSHOT suffix replaced with the build qualifier.

7. Exercise: Tycho build for products

7.1. Target of this exercise

The following exercise demonstrates how to build Eclipse products with Maven Tycho. It is based on the [exercisetychoplugin] and [exercisetychofeature] exercises.

7.2. Creating a plug-in and the product project

Use the File ▸ New ▸ Other…​ ▸ Plug-in Development ▸ Plug-in Project menu entry and create a plug-in in the bundles folder. Call this plug-in com.vogella.tycho.rcp and use the Eclipse 4 RCP application template.

Eclipse RCP plug-in creation

Create a new project of type General called com.vogella.tycho.product in the releng folder.

Eclipse project for the product creation

Move your .product file from the com.vogella.tycho.rcp file into this new project.

Tycho product setup

7.3. Enter ID in the product

To build your product with Tycho, you need to enter the ID on the product configuration file.

Entering the product ID in the product configuration file

7.4. Create poms

You do not need to create a pom file for your com.vogella.tycho.rcp plug-in as the default pom is sufficient.

Default pom for products are not yet supported (see Bug report), therefore create a pom file for your product.

<project>
 <modelVersion>4.0.0</modelVersion>
 <parent>
  <groupId>com.vogella.tycho</groupId>
  <artifactId>com.vogella.tycho.releng</artifactId>
  <version>1.0.0-SNAPSHOT</version>
 </parent>

    <groupId>com.vogella.tycho</groupId>
 <artifactId>com.vogella.tycho.product</artifactId>
 <packaging>eclipse-repository</packaging>
 <version>1.0.0-SNAPSHOT</version>

 <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>

7.5. Change product to use features

Change your product configuration file to be based on features.

Switch product to features
Switch product to features

7.6. Enable separate update of the custom feature

Open the product file and add `installMode="root"`for the feature. This allows to update the feature separately.

<?xml version="1.0" encoding="UTF-8"?>
<?pde version="3.5"?>

<product name="com.vogella.tycho.rcp" uid="Tycho" id="com.vogella.tycho.rcp.product" application="org.eclipse.e4.ui.workbench.swt.E4Application" version="1.0.0.qualifier" useFeatures="true" includeLaunchers="true">

   <configIni use="default">
   </configIni>

   <launcherArgs>
      <programArgs>-clearPersistedState
      </programArgs>
      <vmArgsMac>-XstartOnFirstThread -Dorg.eclipse.swt.internal.carbon.smallFonts
      </vmArgsMac>
   </launcherArgs>

   <windowImages/>

   <plugins>
   </plugins>

   <features>
      <feature id="org.eclipse.e4.rcp" installMode="root"/>
      <feature id="com.vogella.tycho.feature" version="1.0.0.qualifier"/>
      <feature id="org.eclipse.emf.ecore"/>
      <feature id="org.eclipse.emf.common"/>
   </features>

   <configurations>
      <plugin id="org.eclipse.core.runtime" autoStart="false" startLevel="2" />
      <plugin id="org.eclipse.equinox.ds" autoStart="false" startLevel="3" />
      <plugin id="org.eclipse.equinox.event" autoStart="false" startLevel="3" />
   </configurations>

</product>

7.7. Enter start-level in the product

To ensure that your product can be executed after the build, set the start levels and the auto-start flag for important plug-ins. You can do this via the 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
product start level
If you get the following stack trace, when starting the built product, you likely have an incorrect start-level configuration.
java.lang.IllegalStateException: Unable to acquire application service. Ensure that the org.eclipse.core.runtime bundle is resolved and started (see config.ini).
        at org.eclipse.core.runtime.internal.adaptor.EclipseAppLauncher.start(EclipseAppLauncher.java:78)
        at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:388)
        at org.eclipse.core.runtime.adaptor.EclipseStarter.run(EclipseStarter.java:243)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
        at java.lang.reflect.Method.invoke(Method.java:497)
        at org.eclipse.equinox.launcher.Main.invokeFramework(Main.java:673)
        at org.eclipse.equinox.launcher.Main.basicRun(Main.java:610)
        at org.eclipse.equinox.launcher.Main.run(Main.java:1519)

7.8. Update releng pom

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.releng</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <parent>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.root</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <modules>
        <module>com.vogella.tycho.update</module>
        <module>com.vogella.tycho.product</module> (1)
    </modules>
</project>
1 Add the project with the product configuration to the build

7.9. Update bundles pom to include the new rcp plug-in

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.bundles</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <parent>
        <groupId>com.vogella.tycho.example</groupId>
        <artifactId>com.vogella.tycho.example.root</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <modules>
        <module>com.vogella.tycho.plugin1</module>
        <module>com.vogella.tycho.rcp</module> (1)
    </modules>
</project>
1 Adds the rcp plug-in to the bundles build

7.10. Validate setup

Run the build and after the build you find zip and extracted versions of your product in the target/products folder.

Tycho product build result

8. Exercise: Using a target platform for the build

8.1. Create project and target definition file

Create a new project of type General in the releng folder called com.vogella.tycho.target.

Right-click on the new project and select the New ▸ Other ▸ Plug-in Development ▸ Target Definition menu entry. Name the file com.vogella.tycho.target.target.

The name is actually important. It must be the name of the Maven artifact id followed by .target.

Add the Eclipse RCP SDK and Equinox Target Components to your target definition file.

Content of the target definition file

Activate the target definition file in the Eclipse IDE. Of course, Tycho requires that the target platform definition actually works for development. If you have compile errors after activation in the Eclipse IDE, it will also not work for the automatic build.

8.2. Create pom file for the target definition file

Create in a pom file to your com.vogella.tycho.target project.

<project>
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.releng</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.target</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>eclipse-target-definition</packaging>

</project>

8.3. Update releng and configuration pom

Add the new project to your aggregator pom file

<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.vogella.tycho</groupId>
    <artifactId>com.vogella.tycho.releng</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>pom</packaging>

    <parent>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.root</artifactId>
        <version>1.0.0-SNAPSHOT</version>
    </parent>

    <modules>
        <module>com.vogella.tycho.update</module>
        <module>com.vogella.tycho.product</module>
        <module>com.vogella.tycho.target</module>
    </modules>
</project>

Finally activate the usage of the target platform.

<project>
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.vogella.tycho</groupId>
 <artifactId>com.vogella.tycho.configuration</artifactId>
 <version>1.0.0-SNAPSHOT</version>
 <packaging>pom</packaging>

 <properties>
  <tycho.version>0.25.0</tycho.version>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <mars-repo.url>http://download.eclipse.org/releases/mars</mars-repo.url>
 </properties>

 <!-- Repositories should be commented out to only use the target definition (1)
 <repositories>
  <repository>
   <id>mars</id>
   <url>${mars-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>
    <version>${tycho.version}</version>
    <configuration>
     <target> (2)
        <artifact>
            <groupId>com.vogella.tycho</groupId>
            <artifactId>com.vogella.tycho.target</artifactId>
            <version>1.0.0-SNAPSHOT</version>
        </artifact>
    </target>


     <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>
1 This should be commented out or removed, since only the target definition should be used now
2 This block activates the usage of the target definition file

9. Exercise: Tycho build for test plug-ins

9.1. Target of this exercise

The following exercise demonstrates how to run unit tests with Tycho. It is based on the [exercisetychoplugin] and [exercisetychofeature] exercises.

The tests of the implementation belong into a separate plug-in or fragment project. We decide that our software tests should test the API defined by the plug-in, therefore we create a plug-in for the unit tests.

9.2. Adding the test dependencies

For testing usually JUnit is used, but also libraries like Hamcrest and Mockito.

Therefore they are added to the target platform by using the Orbit repository.

The Orbit repository URLs do change quite regulary. Nevertheless the current one for Neon is http://download.eclipse.org/tools/orbit/downloads/drops/R20160520211859/repository/. In case this is not valid any more go to Orbit and look for the latest Orbit repository URL.

So for test purposes the target definition could look like this:

target platform testing

9.3. Create a new tests folder

Create a new tests folder in the root tychoexample folder.

Add the following pom.xml file to the tests folder:

<project>
        <modelVersion>4.0.0</modelVersion>
        <groupId>com.vogella.tycho</groupId>
        <artifactId>com.vogella.tycho.tests</artifactId>
        <version>1.0.0-SNAPSHOT</version>
        <packaging>pom</packaging>

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

        <modules>
                <module>com.vogella.tycho.rcp.tests</module>
        </modules>
</project>

9.4. Create a new plug-in for the tests

Create a new plug-in fragment project called com.vogella.tycho.rcp.tests.

Test plug-in creation for Tycho

Define a dependency to org.junit;bundle-version="4.12.0 and com.vogella.tycho.plugin1 in its MANIFEST.MF file.

Unit test dependencies

The default are sufficient for this test plug-in, hence we need no separate pom for the test plug-in.

9.5. Create a unit test

Create the following unit test, as an example. Of course this test does not test anything real. It is only used to demonstrate how Tycho runs the tests.

package com.vogella.tycho.unittests;

import static org.junit.Assert.*;

import org.junit.Test;

public class ExampleTest {

        @Test
        public void test() {
                // just an example
                assertTrue(true);
        }

}

9.6. Run the build with the tests

Run the build from the main directory. This should work fine.

If you want to skip the test execution use mvn clean verify -DskipTests=true

10. Automatic conversion of JARS to OSGi bundles

In order to convert JARS to OSGi bundles several solutions exist.

10.1. Orbit receipts

The Orbit project hosts the Orbit receipts project which allows to convert JARs from Maven to OSGi bundles. Clone the Git repo from the following URL Orbit Git repos (https://git.eclipse.org/r/orbit/orbit-recipes). Afterwards see the README.md for how to use it. Also see https://github.com/eclipse/ebr for a description of the Eclipse Bundle Recipes project.

10.2. General Eclipse metadata with the p2-maven-plugin

The p2-maven-plugin can be used to generate OSGi bundles out of JARs and to create a p2 update site, which contains the converted OSGi JARs.

With the following build file slf4j-log4j12 in version 1.7.10 and all of its dependencies are be converted to OSGi bundles. Also, a p2 update site is created.

<project>
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.vogella.maven.osgi</groupId>
 <artifactId>com.vogella.maven.osgi.convert</artifactId>
 <version>0.0.1-SNAPSHOT</version>
 <packaging>pom</packaging>

 <build>
  <plugins>
   <plugin>
    <groupId>org.reficio</groupId>
    <artifactId>p2-maven-plugin</artifactId>
    <version>1.1.2-SNAPSHOT</version>
    <executions>
     <execution>
      <id>default-cli</id>
      <configuration>
       <artifacts>
        <!-- specify your depencies here -->
        <!-- groupId:artifactId:version -->
        <artifact>
         <id>org.slf4j:slf4j-log4j12:1.7.10</id>
        </artifact>
       </artifacts>
      </configuration>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>

 <pluginRepositories>
  <pluginRepository>
   <id>reficio</id>
   <url>http://repo.reficio.org/maven/</url>
  </pluginRepository>
 </pluginRepositories>

</project>

By using the mvn clean p2:site goal the following directory structure is created.

p2 maven plugin

Here you can see that also log4j_1.2.17 and slf4j.api_1.7.10 are converted. They can be used via the generated update site.

p2 maven plugin updatesite

In this case the p2 repository targets the file system. But of curse you can also embed the conversion into a deployment build.

In the following sample the p2-maven-plugin is added to the package phase and the site goal is executed. Then the p2 updatesite is archived to one zip file, which is then uploaded to a repository manager.

<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>com.vogella.p2</groupId>
 <artifactId>com.vogella.p2</artifactId>
 <version>0.0.1-SNAPSHOT</version>
 <packaging>pom</packaging>

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

 <distributionManagement>
  <repository>
   <id>deployment</id>
   <name>Internal Releases</name>
   <url>http://localhost:8081/nexus/content/repositories/releases/</url>
  </repository>
  <snapshotRepository>
   <id>deployment</id>
   <name>Internal Releases</name>
   <url>http://localhost:8081/nexus/content/repositories/snapshots/</url>
  </snapshotRepository>
 </distributionManagement>

 <build>
  <plugins>
   <!-- create p2 updatesite with specified dependencies -->
   <plugin>
    <groupId>org.reficio</groupId>
    <artifactId>p2-maven-plugin</artifactId>
    <version>1.1.2-SNAPSHOT</version>
    <executions>
     <execution>
      <phase>package</phase>
      <id>default-cli</id>
      <goals>
       <goal>site</goal>
      </goals>
      <configuration>
       <artifacts>
        <!-- specify your depencies here -->
        <!-- groupId:artifactId:version -->
        <artifact>
         <id>org.slf4j:slf4j-log4j12:1.7.10</id>
        </artifact>
       </artifacts>
      </configuration>
     </execution>
    </executions>
   </plugin>
   <!-- Zip the P2 repository -->
   <plugin>
    <groupId>org.eclipse.tycho</groupId>
    <artifactId>tycho-p2-repository-plugin</artifactId>
    <version>${tycho.version}</version>
    <executions>
     <execution>
      <phase>package</phase>
      <goals>
       <goal>archive-repository</goal>
      </goals>
     </execution>
    </executions>
   </plugin>

   <!-- Attach zipped P2 repository to be installed and deployed in the Maven
    repository during the deploy phase. -->
   <plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <version>1.8</version>
    <executions>
     <execution>
      <goals>
       <goal>attach-artifact</goal>
      </goals>
      <configuration>
       <artifacts>
        <artifact>
         <file>target/${project.artifactId}-${project.version}.zip</file>
         <type>zip</type>
        </artifact>
       </artifacts>
      </configuration>
     </execution>
    </executions>
   </plugin>
  </plugins>
 </build>

 <pluginRepositories>
  <pluginRepository>
   <id>reficio</id>
   <url>http://repo.reficio.org/maven/</url>
  </pluginRepository>
 </pluginRepositories>

</project>

If you are using an artifact manager like Nexus, you can mvn clean deploy and the zip file is deployed to it.

In order to use this p2 update site inside this zip file you can create a virtual repository on Nexus and use the Tycho/Nexus Unzip Plugin.

See Tycho/Nexus Unzip plugin for more information.

See http://projects.reficio.org/p2-maven-plugin for more information on the usage of the p2-maven-plugin. == More Tycho settings

10.3. Using root level features

A root level feature is a feature which can be updated or uninstalled independently of the product.

To define that a feature is a root level feature, add installMode="root" behind the feature in the product definition file. You need to use a text editor for this at the moment, the product configuration editor does currently not expose that in its user interface.

10.4. 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>

If you do not set this encoding property the maven build throws warnings similar to the following: ----  [WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent!

For further information see Maven FAQ for encoding warning (http://maven.apache.org/general.html#encoding-warning).

10.5. Using a repository mirror

You can create p2 repository mirrors, e.g., you can create a mirror of an update site of an Eclipse release. For this you can use the mirrorApplication of Eclipse.

# create artifact mirror via the command line in your Eclipse installation
# on windows use eclipse.exe instead of eclipse
eclipse -application org.eclipse.equinox.p2.artifact.repository.mirrorApplication
   -source http://download.eclipse.org/releases/mars
   -destination file:/home/vogella/marsclone

eclipse -application org.eclipse.equinox.p2.metadata.repository.mirrorApplication
   -source http://download.eclipse.org/releases/mars
   -destination file:/home/vogella/marsclone

To use your mirror, configure Maven to use it via the settings.xml file in your home folder.

<settings>
 <mirrors>
  <mirror>
   <id>Mars_mirror</id>
   <mirrorOf>Mars</mirrorOf>
   <name>Local mirror of Mars repository</name>
   <url>file://home/vogella/Marsclone</url>
   <layout>p2</layout>
   <mirrorOfLayouts>p2</mirrorOfLayouts>
  </mirror>
 </mirrors>
</settings>

10.6. Removing compiler warning messages from the build

You can remove compiler warnings from the Maven build by configuring the tycho-compiler-plugin. This is demonstrated with the following snippet.

<build>
    <plugins>
      <plugin>
        <groupId>org.eclipse.tycho</groupId>
        <artifactId>tycho-compiler-plugin</artifactId>
        <version>${tycho.version}</version>
        <configuration>
          <compilerArgs>
            <arg>-warn:-raw,unchecked</arg>
          </compilerArgs>
        </configuration>
      </plugin>
    </plugins>
 </build>

10.7. Using the last Git commit as build qualifier special build settings

You can configure the tycho-packaging-plugin to use the last Git commit as build qualifier instead of the build time. The following pom file shows how to do this. This allows building reproducible results if no change happened in the Git repository. This only works if the project is in a Git repository.

<project>
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.vogella.tycho.jgit.plugin</groupId>
 <artifactId>com.vogella.tycho.jgit.plugin</artifactId>
 <version>1.0.0-SNAPSHOT</version>

 <packaging>eclipse-plugin</packaging>

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

 <repositories>
  <repository>
   <id>neon</id>
   <url>${neon-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>

10.8. Generating and updating POM files for Eclipse components

10.8.1. Generating POM files

Tycho supports the generation of POM files via its tycho-pomgenerator-plugin:generate-poms goal. This goals search from the existing directory for Eclipse components which do not yet have a pom files and generates them.

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

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

This command generates pom files for all Eclipse components below the current directory and a parent pom in the current directory which includes all Eclipse components as modules.

For identifying test bundles the generator assumes that those bundles have .test as suffix.  By using -DtestSuffix=.mytestBundleSuffix as additional parameter you can override this default.

If you try to execute this generated pom file, the build fail because you have not yet configured your dependencies.

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 and define from which directory it should start.

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

10.9. Update POM files with new version number

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

10.10. Setting version numbers

After releasing an application or several plug-ins, the version number should be increased. If you do not use pomless builds, there are two locations where version numbers are defined. On the one hand the pom.xml file and on the other hand the MANIFEST.MF file.

This can be done easily by using the Tycho Versions Plugin.

# setting the version in pom.xml and MANIFEST.MF files
mvn org.eclipse.tycho:tycho-versions-plugin:set-version -DnewVersion=X.Y.Z
        -Dtycho.mode=maven

Eclipse usually uses semantic versioning for plug-ins, so a version number like {major}.{minor}.{patch} is used. See Semantic versioning for more information.

The tycho.mode=maven property disables the target platform calculation and dependency resolution, which is usually done by Tycho. This results in better performance, since those features are not necessary for updating the version.

More information about versioning with Tycho can be found in the Tycho version wiki.

10.11. Signing plug-ins

If the user installs plug-ins which are not signed, the user received a warning that the plug-in is not signed.

The Tycho build system allows to sign plug-ins and executables. You can purchase a certificate from a certification authority or create your own signature and use this for signing. If you use a custom generated certificate the user receives a warning that the certificate is not official.

For testing a self-generated certificate is sufficient. You can generate such a certificate on the command line with the keytool from the Java Development Kit. This requires that the corresponding directory is in your current execution path.

# the following goes in one line

keytool -genkey -alias   -keystore eclipse-signing.keystore \
-storepass PASSWORD -validity 4360

# this command triggers a set of questions

What is your first and last name?
  [Unknown]:  Jim Knopf
What is the name of your organizational unit?
  [Unknown]:  IT
What is the name of your organization?
  [Unknown]:  test Company
What is the name of your City or Locality?
  [Unknown]:  Hamburg
What is the name of your State or Province?
  [Unknown]:  Germany
What is the two-letter country code for this unit?
  [Unknown]:  DE
Is CN=Jim Knopf, OU=IT, O=test Company, L=Hamburg, ST=Germany, C=DE correct?
  [no]:  y

Enter key password for <selfsigned>
    (RETURN if same as keystore password):

To sign the plug-ins add the configuration for the maven-jarsigner-plugin

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jarsigner-plugin</artifactId>
    <version>1.2</version>
        <configuration>
            <keystore>file:///home/vogella/eclipse-signing.keystore</keystore>
                <storepass>voclipse</storepass>
                    <alias>selfsigned</alias>
                      <keypass>PASSWORD</keypass>
        </configuration>
        <executions>
            <execution>
                <id>sign</id>
                <goals>
                    <goal>sign</goal>
                </goals>
            </execution>
         </executions>
</plugin>

10.12. Building native components

Building native components, for example based on C or C++ code, is typically done via antrunner calling the native build system like make.

See the following commit for an example:

11. Tycho and m2e

To use the Eclipse m2e plug-in easily with Tycho, it is recommended to install the M2E Tycho connectors.

You find the latest version of this connector via the following update site:

http://repo1.maven.org/maven2/.m2e/connectors/m2eclipse-tycho/0.8.0/N/LATEST/ == Automatic deployment of a p2 update site with Maven

You can use the Maven Wagon plug-in to deploy your artifacts, e.g., to an ftp server.

To define the credentials to login to the server you can 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 file to use the wagon plug-in 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.

<project>
  <modelVersion>4.0.0</modelVersion>

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

  <artifactId>com.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

12. Deploy p2 updatesite to Nexus

12.1. Setup Distribution Management

When a Nexus is installed on localhost, the following Distribution Management will likely be used:

<project>
 <distributionManagement>
  <repository>
   <id>nexus</id>
   <name>Internal Releases</name>
   <url>http://localhost:8081/nexus/content/repositories/releases/</url>
  </repository>
  <snapshotRepository>
   <id>nexus</id>
   <name>Internal Snapshots</name>
   <url>http://localhost:8081/nexus/content/repositories/snapshots/
   </url>
  </snapshotRepository>
 </distributionManagement>
</project>

12.2. Credentials for the Nexus repository manager

To define the credentials to login to the Nexus Server you can 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>nexus</id>
      <username>admin</username>
      <password>admin123</password>
    </server>
  </servers>
  <mirrors/>
  <proxies/>
  <profiles/>
  <activeProfiles/>
</settings>

The id in the setting file must fit to the id of the repository in the Distribution Management. Both are named nexus in this example.

12.3. Only deploy the p2 update site

When using mvn clean deploy usually all build artifacts of all modules are deployed to the Nexus. In the context of Tycho build, you usually want to deploy only the p2 update site, since its content is used by the target definitions or for application updates.

In order to archive this the deploy phase can be skipped by using maven.deploy.skip property in the root parent pom.

<properties>
        <tycho.version>0.25.0</tycho.version>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <!-- Skip the deployment here, submodules can override this property -->
        <maven.deploy.skip>true</maven.deploy.skip>
</properties>

This property will be derived by all child modules so that they are not deployed unless a child module overrides this property. And this is supposed to be done in the p2 update site module.

So this property should be false for all p2 update site modules.

<properties>
        <!-- Do not skip the deployment here since we want this module to be deployed -->
        <maven.deploy.skip>false</maven.deploy.skip>
</properties>

13. About this website

14. Eclipse Tycho resources

http://takari.io/2015/03/19/core-extensions.html - Blog post about Maven core extensions introduction

git://git.eclipse.org/gitroot/tycho/org.eclipse.tycho-demo.git - Git repository for Tycho examples

14.1. vogella GmbH training and consulting support

TRAINING SERVICE & SUPPORT

The vogella company provides comprehensive training and education services from experts in the areas of Eclipse RCP, Android, Git, Java, Gradle and Spring. We offer both public and inhouse training. Whichever course you decide to take, you are guaranteed to experience what many before you refer to as “The best IT class I have ever attended”.

The vogella company offers expert consulting services, development support and coaching. Our customers range from Fortune 100 corporations to individual developers.

Copyright © 2012-2016 vogella GmbH. Free use of the software examples is granted under the terms of the EPL License. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.

See Licence.