This tutorial describes the usage of the Maven Tycho plug-in to build plug-ins, bundles and Eclipse applications. It uses Tycho is version 1.6.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.
For a description on how to install and use Maven on the command line see the Apache Maven tutorial.
2. Using Maven Tycho to build Eclipse components
2.1. High level overview of Tycho
Tycho is a set of Maven plug-ins for building Eclipse plug-ins, features, products and OSGi bundles. These elements are called modules. A Tycho build is configured via one or multiple pom.xml files.
Typical, you would create at least two pom files:
-
a configuration pom file (configuration pom) which defines the build configuration
-
a pom file which lists all modules which are part of the build.
Each module could define its own pom file or use Tycho functionality to calculate this data based on other existing meta data.
2.2. Defining the dependencies for the build
By default, all components included in the build are available to resolve dependencies. For additional dependencies, you need to specify where these dependencies can be found.
This can be done via:
-
the specification of p2 update sites in the pom.xml file or
-
the specification of a target platform which should be used for the build in the pom.xml file
If you specify a p2 update site as target, the whole content of all defined p2 repositories becomes part of the target platform. If you want to make a p2 update site available in the build add the following snippet to your pom.xml configuration file.
<repositories>
<repository>
<id>eclipse-mars</id>
<url>http://download.eclipse.org/releases/latest</url>
<layout>p2</layout>
</repository>
</repositories>|
Tycho only supports Software Sites as locations for target definition files. The Directory Installation and Feature entries are not supported by Tycho and are ignored by the build process. |
|
The target editor tends to pick up the exact version of the plug-in from the update site. In case you are building against dynamically changing p2 repositories, you can specify that the version is not important. In this case use "0.0.0" as version qualifier. This change needs to be done, via a text 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. |
3. Executing plug-in unit tests with Tycho
3.1. Configuration for the test execution
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 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 want to run UI tests, you have to enable 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 in features ("eclipse-feature"), plug-ins or fragments ("eclipse-plugin") or installable units ("p2-installable-unit"). If you define a dependency you need to include their transitive dependencies in the test runtime, too.
<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.vogella.feature1</artifactId>
<!-- This is the minimum required version -->
<version>1.0.0</version>
</dependency>
</dependencies>
</configuration>
</plugin>
</plugins>
</build>
</project>3.2. Selection of tests
Similar to the Maven Surefire plug-in, Tycho Surefire 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.3. 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 the build process was started with a Java 7 JVM.
This does not work 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 the test bundle requires Java 8 for example, you must start the build process in a Java 8 JVM.
4. Exercise: Configuring a Tycho build for a RCP application
In this exercise, you configure Tycho for your Eclipse RCP application. The description assumes that all artifacts are placed in the same top-level directory.
4.1. Components to build
The following lists the components which will be part of this build. You may have created them already, if not use the Eclipse wizard to create these artifacts.
In this exercise, you configure Tycho for your set of Eclipse artifacts.
| ID of the artifact | Type |
|---|---|
com.vogella.tasks.ui |
plug-in / bundle |
com.vogella.tasks.feature |
feature |
com.vogella.tasks.product |
product |
com.vogella.tasks.model |
plug-in / bundle |
com.vogella.tasks.services |
plug-in/ bundle |
You may have more components, but using the above list contains all different components for your RCP application. If you have more components you can simply add them to the master pom file on the root level as you see soon.
4.2. Enable pomless Tycho build
Create in the main directory in which all your Eclipse artifacts are, a new director called .mvm. In this folder create a new file extensions.xml.
The content of the .mvn/extensions.xml must look like the following:
<extensions>
<extension>
<groupId>org.eclipse.tycho.extras</groupId>
<artifactId>tycho-pomless</artifactId>
<version>1.6.0</version>
</extension>
</extensions>4.3. Create releng pom for the build configuration
Releng stands typically for release engineering.
Create a new project of type General called releng in the main directory.
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>1.6.0</tycho.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<eclipse-repo.url>http://download.eclipse.org/releases/latest</eclipse-repo.url>
</properties>
<repositories>
<repository>
<id>eclipse-release</id>
<url>${eclipse-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>
<!--Enable the replacement of the SNAPSHOT version in the final product configuration-->
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-packaging-plugin</artifactId>
<version>${tycho.version}</version>
<executions>
<execution>
<phase>package</phase>
<id>package-feature</id>
<configuration>
<finalName>${project.artifactId}_${unqualifiedVersion}.${buildQualifier}</finalName>
</configuration>
</execution>
</executions>
</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_64</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.4. 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>root</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<parent>
<groupId>com.vogella.tycho</groupId>
<artifactId>releng</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>./releng</relativePath>
</parent>
<modules>
</modules>
</project>4.5. Validate build setup
Run the build via mvn clean verify, this build should be successful.
No build artifact is created.
The output should be similar to the following:
[INFO] Scanning for projects...
[INFO]
[INFO] -----------------------< com.vogella.tycho:root >-----------------------
[INFO] Building root 1.0.0-SNAPSHOT
[INFO] --------------------------------[ pom ]---------------------------------
[INFO]
[INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ root ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.117 s
[INFO] Finished at: 2020-02-24T16:26:38+01:005. Exercise: Configure your modules
Now add all relevent modules to your pom file in the root diretory.
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.vogella.tycho</groupId>
<artifactId>root</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<parent>
<groupId>com.vogella.tycho</groupId>
<artifactId>releng</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>./releng</relativePath>
</parent>
<modules>
<module>com.vogella.tasks.ui</module>
<module>com.vogella.tasks.feature</module>
<module>com.vogella.tasks.product</module>
<module>com.vogella.tasks.model</module>
<module>com.vogella.tasks.services</module>
</modules>
</project>6. Exercise: Validate the build
Press F5 in the Eclipse IDE on your feature project to refresh it.
You should 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.1. Run the build
Run the build from the main directory via the following command:
mvn clean verifyThis should result in a success message.
6.2. Error resolution
If Tycho can not find a required plug-in or feature it gives an error message. The following is an example for a feature that requires a bundle but this bundle is not part of the build.
[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 foundIf 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.
In this case you need to either add the required module to the build or if you consume it in binary form, add it to the target platform.
7. Exercise: Tycho build for update sites
The following exercise demonstrates how to build Eclipse p2 update sites with Maven Tycho.
7.1. Create a category definition file for the update site
Create a new project of type General called releng-updatesite.
Right-click on this project and select . Call this file category.xml.
Press the New Category button and create a new category with the :
-
com.vogella.tasks.updateID -
"Task management update site" name.
Press the Add Feature… button and include your feature project into the category.
7.2. Update the root pom
Add your new module to your root pom file.
<modules>
<!-- all modules as before -->
<module>releng-updatesite</module> (1)
</modules>| 1 | Adds the releng-updatesite pom to the aggregator build |
7.3. Run aggregator build and validate the update site build result
Run the build from your main directory. It should complete successfully and build all your components including the update site.
Press F5 in the Eclipse IDE on your update site project to refresh it. You should find a new target folder in your project which contains a repository folder. This folder contains the update site.
Validate that the SNAPSHOT suffix of the JAR files in the repository directory was replaced with the build qualifier.
8. Exercise: Tycho build for products
The following exercise demonstrates how to build Eclipse products with Maven Tycho.
8.1. Creating a plug-in and the product project
Use the menu entry and create a plug-in in the bundles folder. Name this plug-in com.vogella.tycho.rcp and use the Eclipse 4 RCP application template.
Create a new project of type General called com.vogella.tycho.product in the releng folder.
Move your .product file from the com.vogella.tycho.rcp file into this new project.
8.2. Enter ID in the product
To build your product with Tycho, you need to enter the ID on the product configuration file.
8.3. 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>
8.5. 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
| 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)8.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>8.7. 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 |
8.8. 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 |
8.9. Validate setup
Run the build and after the build you find zip and extracted versions of your product in the target/products folder.
9. Exercise: Tycho build for products with root files
In some cases it is helpful, if additional static files, like a readme.txt or logback.xml file, can be added to the built product. The easiest way to archive this, is to use root properties in the build.properties file a feature project.
| Further information about root file properties can be found here: Adding Files to the Root of a Build |
9.1. Adding a static file to a feature
Create a readme.txt file in the com.vogella.tycho.feature project.
9.2. Include the readme.txt file
To include this file in the product, the existing build.properties file of the com.vogella.tycho.feature project has to be adjusted by a root file property.
bin.includes = feature.xml
root = file:readme.txt9.3. Validate
Run the mvn clean verify command. There should be a readme.txt file inside the built product.
10. Exercise: Using a target platform for the build
10.1. Create project and target definition file
Create a new project of type General in the releng folder called target-definition.
Right-click on the new project and select the menu entry. Name the file eclipse-2019-03.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.
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. |
10.2. Create pom file for the target definition file
Create a pom file in your target-definition 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>eclipse-2019-03</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>eclipse-target-definition</packaging>
</project>10.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>target-definition</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>1.2.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>eclipse-repo</id>
<url>${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>eclipse-2019-03</artifactId>
<version>1.0.0-SNAPSHOT</version>
</artifact>
</target>
<environments>
<environment>
<os>linux</os>
<ws>gtk</ws>
<arch>x86_64</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 |
11. Exercise: Tycho build for test plug-ins
The following exercise demonstrates how to run unit tests with Tycho.
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.
11.1. Adding the test dependencies
For testing usually JUnit is used, but also libraries like Hamcrest and Mockito are possible.
Therefore they are added to the target platform by using the Orbit repository.
| The Orbit repository URLs do change quite regularly. 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. |
For test purposes the target definition could look like this:
11.2. 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>11.3. Create a new plug-in for the tests
Create a new plug-in fragment project called com.vogella.tycho.rcp.tests.
Define a dependency on org.junit;bundle-version="4.12.0 and com.vogella.tycho.plugin1 in its MANIFEST.MF file.
The defaults are sufficient for this test plug-in, hence we need do not need a separate pom for the test plug-in.
11.4. 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);
}
}11.5. 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
11.6. Debug Maven Tycho tests via Eclipse
To debug Maven Tycho tests, add the -DdebugPort=8000 parameter to your Maven build command.
Maven will pause during execution and you can create a Remote Java Application debug configuration to connect to the test.
12. Exercise: Tycho build for SWTBot tests
The following exercise demonstrates how to run SWTBot tests with Tycho.
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.
12.1. Adding the test dependencies
The dependencies for JUnit, Hamcrest and Mockito will be reused in this exercise.
The latest version of SWT bot can be obtained from this update site: http://download.eclipse.org/technology/swtbot/releases/latest/
12.2. Create a new plug-in for the tests
Create a new plug-in fragment project called com.vogella.tycho.rcp.it.tests, where "it" stands for integration test.
Define a dependency on org.junit;bundle-version="4.12.0, org.hamcrest;bundle-version="1.3.0", org.eclipse.swtbot.junit4_x;bundle-version="2.3.0" and org.eclipse.swtbot.swt.finder;bundle-version="2.3.0" in its MANIFEST.MF file.
12.3. Create a unit test
Create the following SWTBot test.
package com.vogella.tycho.rcp.it.tests.swtbot;
import static org.hamcrest.MatcherAssert.assertThat;
import static org.hamcrest.Matchers.not;
import org.eclipse.swtbot.swt.finder.SWTBot;
import org.eclipse.swtbot.swt.finder.junit.SWTBotJunit4ClassRunner;
import org.eclipse.swtbot.swt.finder.widgets.SWTBotMenu;
import org.junit.BeforeClass;
import org.junit.Test;
import org.junit.runner.RunWith;
@RunWith(SWTBotJunit4ClassRunner.class)
public class TestMenus {
private static SWTBot bot;
@BeforeClass
public static void beforeClass() throws Exception {
// don't use SWTWorkbenchBot here which relies on Platform 3.x
bot = new SWTBot();
}
@Test
public void ensureSaveIsDisabledWhenNothingIsDirty() {
SWTBotMenu menu = bot.menu("File").menu("Save");
assertThat("Save command in menu is not enabled", not(menu.isEnabled()));
}
}In the @BeforeClass method a static reference to a SWTBot instance, which will be used for all test methods, is created.
SWTBot needs a special test runner, which is applied by annotating the test class with @RunWith(SWTBotJunit4ClassRunner.class).
12.4. Pom file for SWTBot tests
Another difference for integration tests, like SWTBot tests, is that the Tycho Surefire plug-in has to be configured, so that the SWTBot test can run properly.
<?xml version="1.0" encoding="UTF-8"?>
<project
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.vogella.tycho</groupId>
<artifactId>com.vogella.tycho.tests</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<artifactId>com.vogella.tycho.rcp.it.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>
<useUIThread>false</useUIThread>
<product>com.vogella.tycho.rcp.product</product>
<application>org.eclipse.e4.ui.workbench.swt.E4Application</application>
</configuration>
</plugin>
</plugins>
</build>
</project>12.5. Adding org.eclipse.equinox.event as extra requirement
In most of the cases the org.eclipse.equinox.event plug-in is used in an Eclipse RCP application.
Unfortunately it sometimes is not loaded properly for an integration test, even though it is part of the target platform of the product and mentioned in the start level configuration.
Due to this it needs to be specified in the configuration of the target-platform-configuration plugin.
<project>
<build>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>target-platform-configuration</artifactId>
<version>${tycho.version}</version>
<configuration>
<!-- This defines the target definition file -->
<target>
<artifact>
<groupId>com.vogella.tychoexample</groupId>
<artifactId>com.vogella.build.targetdefinition</artifactId>
<version>1.0.0-SNAPSHOT</version>
</artifact>
</target>
<dependency-resolution>(1)
<extraRequirements>
<requirement>
<type>eclipse-plugin</type>
<id>org.eclipse.equinox.event</id>
<versionRange>0.0.0</versionRange>
</requirement>
</extraRequirements>
</dependency-resolution>
<environments>
<environment>
<os>linux</os>
<ws>gtk</ws>
<arch>x86_64</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 | Add the org.eclipse.equinox.event plug-in as extra requirement in the dependency resolution. |
12.6. Add the SWTBot test to the build
The com.vogella.tycho.rcp.it.tests plug-in has to be added to the pom.xml of the tests folder to take part in the overall build.
<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>
<module>com.vogella.tycho.rcp.it.tests</module>
</modules>
</project>13. More Tycho settings
13.1. 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.
13.2. 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, but we recommend to use the latest versions.
The contents of the .mvn/extensions.xml must look like this:
<extensions>
<extension>
<groupId>org.eclipse.tycho.extras</groupId>
<artifactId>tycho-pomless</artifactId>
<version>1.6.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.
| 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 |
13.3. 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.
|
The build requires that the version numbers of each single Maven artifacts and its Eclipse plug-ins are in sync. Sometimes (this is rare these days) developers forget to update the Maven version numbers. In this case the build complains about a version mismatch. Run the following command to correct existing inconsistencies. |
This attribute defines what kind of Eclipse component you are building.
For example, a plug-in must set this attribute to eclipse-plugin.
| 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.vogella.imageloader.services</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>eclipse-plugin</packaging>
</project>13.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).
13.5. Building source features
Tycho generates source features on the fly, so you do not need to create any additional projects.
<!-- enable source feature generation -->
<plugin>
<groupId>org.eclipse.tycho.extras</groupId>
<artifactId>tycho-source-feature-plugin</artifactId>
<version>${tycho.version}</version>
<executions>
<execution>
<id>source-feature</id>
<phase>package</phase>
<goals>
<goal>source-feature</goal>
</goals>
</execution>
</executions>
<configuration>
<excludes>
<!-- provide plug-ins not containing any source code -->
<plugin id="com.vogella.tycho.product" />
<plugin id="com.vogella.tycho.target" />
<plugin id="com.vogella.tycho.update" />
</excludes>
</configuration>
</plugin>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-source-plugin</artifactId>
<version>${tycho.version}</version>
<executions>
<execution>
<id>plugin-source</id>
<goals>
<goal>plugin-source</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- -->
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-p2-plugin</artifactId>
<version>${tycho.version}</version>
<executions>
<execution>
<id>attach-p2-metadata</id>
<phase>package</phase>
<goals>
<goal>p2-metadata</goal>
</goals>
</execution>
</executions>
</plugin>You can add the generated source features to your existing updates side.
For this, open the category file and add the features and plug-ins to one of your categories with the .sources suffix.
<?xml version="1.0" encoding="UTF-8"?>
<site>
<feature id="com.vogella.tycho.feature" version="0.0.0">
<category name="tychoexample"/>
</feature>
<feature id="com.vogella.tycho.feature.source" version="0.0.0">
<category name="tychoexample-source"/>
</feature>
<category-def name="tychoexample" label="Tycho example"/>
<category-def name="tychoexample-source" label="Tycho example source bundles"/>
</site>13.6. Mirroring a remote update site
Tycho allows to mirror a remote update site. This reduces the dependency to the remote side as you can use your local copy for building the Eclipse application.
The following is an example for such a mirror task.
<?xml version="1.0" encoding="UTF-8"?>
<project
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"
xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<name>Mirror Update Site</name>
<prerequisites>
<maven>3.0</maven>
</prerequisites>
<groupId>com.vogella.p2.mirror</groupId>
<artifactId>mirror</artifactId>
<version>3.5.0-SNAPSHOT</version>
<packaging>pom</packaging>
<properties>
<tycho.version>1.0.0</tycho.version>
<tycho-extras.version>1.0.0</tycho-extras.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho.extras</groupId>
<artifactId>tycho-p2-extras-plugin</artifactId>
<version>${tycho.version}</version>
<executions>
<execution>
<phase>prepare-package</phase>
<goals>
<goal>mirror</goal>
</goals>
</execution>
</executions>
<configuration>
<source>
<!-- source repositories to mirror from -->
<repository>
<url>http://download.eclipse.org/releases/2018-09/</url>
<layout>p2</layout>
<!-- supported layouts are "p2-metadata", "p2-artifacts", and "p2" (for joint repositories; default) -->
</repository>
</source>
<!-- starting from here all configuration parameters are optional -->
<!-- they are only shown here with default values for documentation purpose -->
<!-- List of IUs to mirror. If omitted, allIUs will be mirrored. -->
<!-- Omitted IU version element means latest version of the IU -->
<ius>
<iu>
<id>org.eclipse.rcp.feature.group</id>
</iu>
</ius>
<!-- The destination directory to mirror to. -->
<destination>${project.build.directory}/repository</destination>
<!-- Whether only strict dependencies should be followed. -->
<!-- "strict" means perfect version match -->
<followStrictOnly>false</followStrictOnly>
<!-- Whether or not to follow optional requirements. -->
<includeOptional>true</includeOptional>
<!-- Whether or not to follow non-greedy requirements. -->
<includeNonGreedy>true</includeNonGreedy>
<!-- Filter properties. E.g. filter only one platform -->
<filter>
<osgi.os>linux</osgi.os>
<osgi.ws>gtk</osgi.ws>
<osgi.arch>x86_64</osgi.arch>
</filter>
<!-- Whether to filter the resulting set of IUs to only -->
<!-- include the latest version of each IU -->
<latestVersionOnly>false</latestVersionOnly>
<!-- don't mirror artifacts, only metadata -->
<mirrorMetadataOnly>false</mirrorMetadataOnly>
<!-- whether to compress the content.xml/artifacts.xml -->
<compress>true</compress>
<!-- whether to append to the target repository content -->
<append>true</append>
<!-- whether to mirror pack200 artifacts also. Available since tycho-extras 0.17.0 -->
<includePacked>true</includePacked>
</configuration>
</plugin>
</plugins>
</build>
</project>You would execute this task independently of your build and use the newly created local folder in your normal build.
To use your mirror, configure Maven to use it via the settings.xml file in your home folder. Alternatively you can adjust your target definition file to point to the mirror.
<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>13.7. 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>13.8. 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>1.2.0</tycho.version>
<tycho-extras.version>1.2.0</tycho-extras.version>
<repo.url>http://download.eclipse.org/releases/2018-12</repo.url>
</properties>
<repositories>
<repository>
<id>eclipse-repo</id>
<url>${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>13.9. Generating and updating POM files for Eclipse components
13.9.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.tychoexampleThis 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_dir13.10. Update the Maven artifact versiond in the pom files based on the MANIFEST.MF
If you are using individual pom files, you can update their numbers based on the versions in the `MANIFEST.MF`file. To do this, run the following commands.
# update pom files
mvn org.eclipse.tycho:tycho-versions-plugin:update-pom
-Dtycho.mode=maven13.11. 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=mavenEclipse usually uses semantic versioning for plug-ins, so a version number like {major}.{minor}.{patch} is used. See Semantic versioning for more information.
|
The |
More information about versioning with Tycho can be found in the Tycho version wiki.
13.12. Unpack built plug-ins
In case a plug-in contains native code, e.g., dll files or others, which do not work from inside a JAR file, the plug-in itself should be unpacked.
To archive that the plug-in’s MANIFEST.MF must consist of the following property.
Eclipse-BundleShape: dirWith this property in the MANIFEST.MF file the plug-in won’t be packed as JAR file, but just be available as directory in the plugins directory of a product.
13.13. 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>13.14. Building platform specific fragments or bundles
When building a fragment for a certain operating system, you need to override the <environments> configuration from your parent POM. This requires a pom file in fragment or bundle.
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.vogella.tycho</groupId>
<artifactId>com.vogella.tycho.example.linux.x86_64</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<parent>
<groupId>com.vogella.tycho</groupId>
<artifactId>org.eclipse.tycho.parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<build>
<plugins>
<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_64</arch>
</environment>
</environments>
</configuration>
</plugin>
</plugins>
</build>
</project>The following entries are possible:
-
Linux
<configuration>
<environments>
<environment>
<os>linux</os>
<ws>gtk</ws>
<arch>x86_64</arch>
</environment>
</environments>
</configuration>-
Mac
<configuration>
<environments>
<environment>
<os>macosx</os>
<ws>cocoa</ws>
<arch>x86_64</arch>
</environment>
</environments>
</configuration>-
Windows
<configuration>
<environments>
<environment>
<os>win32</os>
<ws>win32</ws>
<arch>x86_64</arch>
</environment>
</environments>
</configuration>13.15. Shell script for generating pom files
Sometimes it is useful to generate the pom files automatically. Here is an example shell script which creates a module entry for each directory in the current directory.
#!/bin/bash
cd $(dirname $0)
BASEDIR=`basename pwd`
echo "Creating pom.xml for $BASEDIR"
cat > pom.xml <<- EOM
<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/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.vogella.tycho</groupId>
<artifactId>$BASEDIR</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<parent>
<groupId>com.vogella.tycho</groupId>
<artifactId>com.vogella.tycho.parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
<modules>
EOM
modules=`ls -l| grep '^d' | awk '{ print "<module>"$9"</module>" }'`
echo "$modules" >> pom.xml
cat >> pom.xml <<- EOM
</modules>
</project>
EOM
cat pom.xml13.16. 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:
14. 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:
15. 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 deployIf 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 uploadRepo16. Deploy p2 updatesite to Nexus
16.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>16.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.
16.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>1.2.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>
Appendix A: Copyright, License and Source code
Copyright © 2012-2019 vogella GmbH. Free use of the software examples is granted under the terms of the Eclipse Public License 2.0. This tutorial is published under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Germany license.