Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Tycho/FAQ
This page is being migrated to: https://github.com/eclipse-tycho/tycho/wiki/Frequently-asked-questions
You may also want to check Frequently asked Tycho questions on stackoverflow.com.
Contents
- 1 Compilation
- 1.1 How do I embed a configurable build version?
- 1.2 How to configure warning/error settings of the OSGi compiler?
- 1.3 How to compile pre-processed source placed in a different directory?
- 1.4 How do I include rootfiles?
- 1.5 How should I define the target platform of my tycho project?
- 1.6 What other options does the Tycho compiler support?
- 1.7 Can I use the Tycho compiler support in non-OSGi projects, too?
- 2 Packaging
- 3 Testing
- 3.1 How to configure HTTP proxy settings during test execution?
- 3.2 How to use SWTBot or some UI tool for testing?
- 3.3 How do I add OS-specific flags?
- 3.4 How to add a undeclared dependency? (e.g., OSGi declarative service)
- 3.5 How do I install the org.eclipse.osgi.compatibility.state fragment?
- 3.6 How do I enable assertions during testing?
- 3.7 How can I debug my tests?
- 3.8 Can I run eclipse-plugin tests also outside an OSGi container?
- 3.9 How do I configure toolchains.xml for use with Jenkins?
- 3.10 How do I test my latest build on a legacy Eclipse installation?
- 4 Diagnosing Build Problems
- 4.1 What does Tycho's message "XXXX" mean?
- 4.2 My build fails with a ClassCastException/NoClassDefFoundError of a Tycho class. What is wrong?
- 4.3 How to switch on HTTP tracing during p2 dependency download?
- 4.4 How to switch on eclipse tracing during test execution?
- 4.5 Why is my app not working?
- 4.6 Why do some images not get updated in the native launcher for Windows?
- 5 Documentation
- 6 In Eclipse IDE
Compilation
How do I embed a configurable build version?
To cause your artifacts to be branded with the a build number, modify your manifests (MANIFEST.MF, feature.xml, etc.) to specify the version as X.Y.Z.qualifier, and the corresponding pom.xml with X.Y.Z-SNAPSHOT. Tycho will replace the qualifier and SNAPSHOT with the build timestamp (in UTC).
You can set the build qualifier to a custom value by setting the forceContextQualifier property. For example:
mvn -DforceContextQualifier=M01 install
You can also set the qualifier by configuring the tycho-packaging-plugin, using some format supported by Java's SimpleDateFormat:
<plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-packaging-plugin</artifactId> <version>${tycho-version}</version> <configuration> <format>'myprefix_'yyyyMMddHHmm</format> </configuration> </plugin>
Tycho does not directly support embedding the build identifier in resources. But some workarounds have been suggested in an email thread on tycho-user.
How to configure warning/error settings of the OSGi compiler?
To configure warnings:
<plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-compiler-plugin</artifactId> <version>${tycho-version}</version> <configuration> <compilerArgument>-warn:[+|-]warning_tokens_separated_by_comma</compilerArgument> </configuration> </plugin>
The available warning tokens are listed in the Eclipse help. Same applies for the
-err
argument for configuring errors.
Alternatively, if you have per-project JDT preferences, you may advise the compiler to use these (see bug 404633 for a simpler solution since Tycho 0.22.0):
<plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-compiler-plugin</artifactId> <version>${tycho-version}</version> <configuration> <compilerArguments> <properties>${project.basedir}/.settings/org.eclipse.jdt.core.prefs</properties> </compilerArguments> </configuration> </plugin>
How to compile pre-processed source placed in a different directory?
In 0.13.0 you can configure your pom.xml with something like the following:
<build> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-compiler-plugin</artifactId> <version>${tycho-version}</version> <configuration> <source>${project.basedir}/YourNewSourceDirectory</source> <usePdeSourceRoots>false</usePdeSourceRoots> </configuration> </plugin> </build>
But... "usePdeSourceRoots" was removed as part of 0.14.0 (see: [1] and [2]).
In 0.16.0 it appears you you must use the build.properties.
How do I include rootfiles?
Tycho provides partial support for PDE-style rootfiles. Rootfiles are associated and installed with a feature. See the product.rootFiles test for an example of using rootfiles.
A different approach is to use the maven-assembly-plugin to assemble a zip file. We do not have a worked example, but Kai Kreuzer documented his approach that was necessary prior to the introduction of rootfile support [3].
How should I define the target platform of my tycho project?
This question is answered here: Tycho/Target Platform
What other options does the Tycho compiler support?
Run this command to get a list of options for your version of Tycho:
mvn help:describe -Dplugin=org.eclipse.tycho:tycho-compiler-plugin -Ddetail
Or you can have a look at the Maven site for Tycho.
Can I use the Tycho compiler support in non-OSGi projects, too?
When compiling regular maven projects (e.g., packaging "jar") the plugin tycho-compiler-jdt
can be used to tell maven to use the JDT compiler (aka "Eclipse Compiler for Java(TM)", "ecj") for compilation. This is useful to ensure that compilation in the IDE and on the build server show the same compiler messages, specifically JDT's annotation-based null analysis can be integrated into the build in this way.
Use the following snippet in your build.pluginManagement.plugins
section:
<plugin>
<!-- Use compiler plugin with tycho as the adapter to the JDT compiler. -->
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.7</source>
<target>1.7</target>
<compilerId>jdt</compilerId>
<compilerArgument>-err:nullAnnot,null</compilerArgument> <!-- insert your warn/err configuration here -->
<!-- see http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm for available options
or instead re-use the exact JDT org.eclipse.jdt.core.compiler properties from *.prefs, like this:
<compilerArguments>
<properties>.settings/org.eclipse.jdt.core.prefs</properties>
NB: It's NOT possible to list *.prefs properties directly here; see https://issues.apache.org/jira/browse/MCOMPILER-123,
so the following in <compilerArguments> does NOT work (unless you contribute to fixing MCOMPILER-123...) :
<org.eclipse.jdt.core.compiler.annotation.nullanalysis>enabled</org.eclipse.jdt.core.compiler.annotation.nullanalysis>
<org.eclipse.jdt.core.compiler.annotation.inheritNullAnnotations>true</org.eclipse.jdt.core.compiler.annotation.inheritNullAnnotations>
-->
</configuration>
<dependencies>
<!-- This dependency provides the implementation of compiler "jdt": -->
<dependency>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-compiler-jdt</artifactId>
<version>${tycho-version}</version>
</dependency>
</dependencies>
</plugin>
Again, a build.plugins.plugin.configuration.compilerArguments.properties
element can be used to reference an existing org.eclipse.jdt.core.prefs
file (see above).
If you use M2E, then in order to address the following errors, it is recommended that you install https://github.com/jbosstools/m2e-jdt-compiler for lifecycle mapping metadata:
- Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-compiler-plugin:3.5.1:compile (execution: default-compile, phase: compile)
- Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-compiler-plugin:3.5.1:testCompile (execution: default-testCompile, phase: test-compile)
Packaging
How to generate Eclipse-SourceReferences MANIFEST header?
See docs. Example for git:
<properties> <tycho.scmUrl>scm:git:https://git.eclipse.org/r/p/egit/egit.git</tycho.scmUrl> </properties> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-packaging-plugin</artifactId> <version>${tycho-version}</version> <configuration> <sourceReferences> <generate>true</generate> </sourceReferences> </configuration> <dependencies> <dependency> <groupId>org.eclipse.tycho.extras</groupId> <artifactId>tycho-sourceref-jgit</artifactId> <version>${tycho-extras-version}</version> </dependency> </dependencies> </plugin>
This will add the Eclipse-SourceReferences header including commit ID used for this build and tag (if present).
How to use OSGi declarative service annotations
See 392764
Testing
The Tycho Surefire plugin runs tests within an OSGi container. The Tycho Reference Card has several examples relating to configuring tests.
How to configure HTTP proxy settings during test execution?
Eclipse tends to override standard command-line proxy settings (log says System property http.proxyHost has been set to proxy.eclipse.org by an external source. This value will be overwritten using the values from the preferences) so more tweaks are required
Several options:
Manually configure the proxy
<build> <plugins> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-surefire-plugin</artifactId> <configuration> <argLine>-Dhttp.proxyHost=myproxy -Dhttp.proxyPort=1234</argLine> </configuration> </plugin> </plugins> </build>
and disable the eclipse system proxy setting
if (Platform.isRunning() && getProxyService() != null && getProxyService().isSystemProxiesEnabled() && !getProxyService().hasSystemProxies()) { // XXX e3.5/gtk.x86_64 activate manual proxy configuration which // defaults to Java system properties if system proxy support is // not available getProxyService().setSystemProxiesEnabled(false); getProxyService().setProxiesEnabled(true); }
- or -
Rely on your OS setting and the native org.eclipse.core.net.* fragment
Make sure the native org.eclipse.core.net.* fragment for your platform is included in the test runtime so eclipse will pick up proxy settings configured on OS level:
<build> <plugins> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-surefire-plugin</artifactId> <configuration> <dependencies> <dependency> <type>p2-installable-unit</type> <artifactId>org.eclipse.core.net.[YOUR_PLATFORM]</artifactId> <version>[VERSION]</version> </dependency> </dependencies> </configuration> </plugin> </plugins> </build>
If you want a multi-platform solution and are not too constrained by dependencies, you can also include the org.eclipse.platform feature that contains the fragment for all supported platforms
<build> <plugins> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-surefire-plugin</artifactId> <configuration> <dependencies> <dependency> <!-- Include org.eclipse.core.net.* fragments, to work with system proxies --> <type>p2-installable-unit</type> <artifactId>org.eclipse.platform.feature.feature.group</artifactId> <version>[VERSION]</version> <!-- or 0.0.0, or even omit this line --> </dependency> </dependencies> </configuration> </plugin> </plugins> </build>
How to use SWTBot or some UI tool for testing?
You need to configure the tycho-surefire-plugin to use the UI:<build> <plugins> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-surefire-plugin</artifactId> <configuration> <useUIHarness>true</useUIHarness> <useUIThread>false</useUIThread> <argLine>-Xms40m -Xmx512m</argLine> </configuration> </plugin> </plugins> </build>
useUIHarness=true ensures the workbench is started before the tests are run. If your app requires a custom application class (viz the org.eclipse.core.runtime.applications extension point), you will likely need to configure the application.
You may wish to add --launcher.suppressErrors to the <appArgLine> element to suppress Eclipse error dialogs.
How do I add OS-specific flags?
Some OS's may require special flags (e.g., SWT on MacOS X). The easiest way is to use a Maven profile to configure a property. For example:
<properties> <os-jvm-flags/> <!-- for the default case --> </properties> <build> <plugins> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-surefire-plugin</artifactId> <version>${tycho-version}</version> <configuration> <useUIHarness>false</useUIHarness> <useUIThread>true</useUIThread> <argLine>-Xms40m -Xmx1G ${os-jvm-flags}</argLine> </configuration> </plugin> </plugins> </build> <profiles> <profile> <id>macosx-jvm-flags</id> <activation> <os><family>mac</family></os> </activation> <properties> <os-jvm-flags>-XstartOnFirstThread</os-jvm-flags> </properties> </profile> </profiles>
Alternatively you could configure the surefire plugins within a profile too.
How to add a undeclared dependency? (e.g., OSGi declarative service)
Use the tycho-surefire-plugin <dependencies> section (see the eclipse-test-plugin packaging type for an example).
How do I install the org.eclipse.osgi.compatibility.state fragment?
A variety of platform services are orchestrated by PlatformAdmin that from Luna onwards is hosted by the org.eclipse.osgi.compatibility.state fragment.
See https://wiki.eclipse.org/Equinox/Luna_Framework#Removal_of_the_PlatformAdmin_Service_Implementation
If you try to use one of these services, your tests may fail with an exit code of -1073740771 and your the target/work/data/.metadata/.log file in your test plugin may have a message of the form:
!MESSAGE The Plug-in Development Environment requires the PlatformAdmin service to operate. Please install the compatibility fragment 'org.eclipse.osgi.compatibility.state'.
You need to add bundle org.eclipse.osgi.compatibility.state as a target-platform-configuration extraRequirement:
<plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>target-platform-configuration</artifactId> <configuration> ... <dependency-resolution> <extraRequirements> <requirement> <type>eclipse-plugin</type> <id>org.eclipse.osgi.compatibility.state</id> <versionRange>[1.1.0,2.0.0)</versionRange> </requirement> </extraRequirements> </dependency-resolution> ... </configuration> </plugin>
How do I enable assertions during testing?
Add an <argLine> to the tycho-surefire-plugin's configuration:
<build> <pluginManagement> <plugins> <plugin> <groupId>org.eclipse.tycho</groupId> <artifactId>tycho-surefire-plugin</artifactId> <version>${tycho-version}</version> <configuration> <argLine>-ea</argLine> </configuration> </plugin> </plugins> </pluginManagement> </build>
How can I debug my tests?
Add -DdebugPort=8000 to your Maven commandline and attach a remote debug session.
See the docs https://www.eclipse.org/tycho/sitedocs/tycho-surefire-plugin/test-mojo.html#debugPort
Can I run eclipse-plugin tests also outside an OSGi container?
Yes. In a project using packaging type eclipse-test-plugin, you can add the following configuration to your pom.xml to also run unit tests outside an OSGI container using maven-surefire-plugin:
<build> <!-- surefire expects test classes in ${project.build.directory}/test-classes by default --> <testOutputDirectory>${project.build.directory}/classes</testOutputDirectory> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-surefire-plugin</artifactId> <version>2.20.1</version> <dependencies> <!-- explicitly declare surefire provider for JUnit4, see http://maven.apache.org/surefire/maven-surefire-plugin/examples/providers.html --> <dependency> <groupId>org.apache.maven.surefire</groupId> <artifactId>surefire-junit4</artifactId> <version>2.20.1</version> </dependency> </dependencies> <executions> <execution> <id>default-test</id> <phase>test</phase> <goals> <goal>test</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
Of course this only makes sense for tests and productive code that should run both inside and outside an OSGi container.
How do I configure toolchains.xml for use with Jenkins?
If you need to use non-standard tools or non-standard versions of standard tools, these may be configured in a toolchains.xml. But how? The recommended location is ~/.m2/toolchains.xml which is not easy to define or share when using Jenkins. By adding
--global-toolchains toolchains.xml
to your Maven command line invocation, you specify that your toolchains.xml can be found at the root of your GIT repository, typically adjacent to your pom.xml.
The following complete toolchains.xml demonstrates how to specify Java 1.5 and Java 1.8 tools. (Trim two leading spaces after cutting and pasting.)
<?xml version="1.0" encoding="UTF-8"?> <toolchains> <toolchain> <type>jdk</type> <provides> <version>1.5</version> <vendor>oracle</vendor> </provides> <configuration> <jdkHome>/opt/tools/java/oracle/jdk-5/latest/bin/java</jdkHome> </configuration> </toolchain> <toolchain> <type>jdk</type> <provides> <version>1.8</version> <vendor>oracle</vendor> </provides> <configuration> <jdkHome>/opt/tools/java/oracle/jdk-8/latest/bin/java</jdkHome> </configuration> </toolchain> </toolchains>
Once these tools have been defined, a particular version may be configured by including the following in your pom.xml.
<maven-toolchains-version>1.1</maven-toolchains-version>
...
<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-toolchains-plugin</artifactId> <version>${maven-toolchains-version}</version> <executions> <execution> <goals> <goal>toolchain</goal> </goals> </execution> </executions> <configuration> <toolchains> <jdk> <version>1.8</version> <vendor>oracle</vendor> </jdk> </toolchains> </configuration> </plugin>
The above defines tool paths that sre suitable for Jenkins and almost certainly not suitable for your local machine. You may define an alternate file, perhaps local-toolchains.xml, with appropriate local paths and use it by specifying it on your maven command line:
--global-toolchains ../../local-toolchains.xml
This may be conveniently appended to the goals of a Maven launch configuration. The "../.." navigates from the working directory of the launch to the local toolchains file.
How do I test my latest build on a legacy Eclipse installation?
Legacy Eclipse platforms such as Oxygen impose a maximum Java version bound of 8.
Current Tycho and Eclipse platforms impose a minimum Java version bound of 11 and probably soon 17.
Naive testing using a single Java version is therefore not possible.
A further complication arises from the latest default Eclipse signer that uses SHA384 rather than SHA256. Tycho versions prior to 2.7.5 are unable to load the OID 1.2.840.113549.1.1.12 for sha384WithRsaEncryption used by the signer.
The option of 'living in the past' with a uniform set of vintage tools fails since they need to load recently signed artefacts.
The solution is to use recent versions of Tycho and Java to download, build and package your products as normal and then to use legacy versions of Java and Eclipse for the legacy testing.
Specifying the legacy Java version is described in #How do I configure toolchains.xml for use with Jenkins?.
Specifying the legacy Eclipse platform requires a target platform definition something like:
<?xml version="1.0" encoding="UTF-8" standalone="no"?><?pde version="3.8"?><target includeMode="feature" name="Eclipse Oxygen Build Target Platform" sequenceNumber="16"> <locations> <location includeAllPlatforms="false" includeConfigurePhase="false" includeMode="planner" includeSource="true" type="InstallableUnit"> <unit id="org.eclipse.sdk.feature.group" version="0.0.0"/> <unit id="org.eclipse.emf.sdk.feature.group" version="0.0.0"/> <unit id="org.eclipse.uml2.sdk.feature.group" version="0.0.0"/> <unit id="org.eclipse.xtext.sdk.feature.group" version="0.0.0"/> <repository location="https://download.eclipse.org/releases/oxygen/201804111000"/> </location> ... </locations> </target>
Diagnosing Build Problems
What does Tycho's message "XXXX" mean?
See the Tycho Messages Explained page.
My build fails with a ClassCastException/NoClassDefFoundError of a Tycho class. What is wrong?
ClassCastExceptions or NoClassDefFoundErrors for Tycho classes most probably indicate that different Tycho versions are used in the same reactor. This is not supported. The problem typically occurs if some of the modules use the incorrect parent POM, e.g. an older version of the correct parent, or if you directly invoke an explicit version of a Tycho goal on the commandline, e.g. mvn org.eclipse.tycho:tycho-versions-plugin:1.1.0:set-version . Check the parent configuration in all modules of the reactor.
How to switch on HTTP tracing during p2 dependency download?
You can enable apache HTTP client tracing for p2 on the maven commandline using
-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog \ -Dorg.apache.commons.logging.simplelog.showdatetime=true \ -Dorg.apache.commons.logging.simplelog.log.org.apache.http=DEBUG \ -Dorg.apache.commons.logging.simplelog.log.org.apache.http.wire=ERROR
How to switch on eclipse tracing during test execution?
Eclipse has a platform tracing mechanism which is switched on by using commandline option -debug and configured by putting a file named .options into the installation root. You can enable this tracing mechanism for tycho test executions by running the build in debug mode using commandline option -X and putting a file .options into the test project root.
E.g. a file .options with content
org.eclipse.osgi/resolver/debug=true org.eclipse.osgi/resolver/wiring=true
will switch on equinox wiring tracing. You may find it useful to use the "tee" command, since running the build in debug mode may generate a lot of output. An example of this syntax is:
cd tests/myPlugin mvn clean install -debug -X | tee testout.txt
Why is my app not working?
Many people post to tycho-user when they are encounter problems attempting to run their deployed applications, where the apps are missing icons, or throwing ClassNotFoundException and NoClassDefFoundError exceptions. Most of these problems are traced to errors in the projects' OSGi/p2 metadata. Some common issues are:
- a bundle declares a runtime dependencies as optional, but the dependency is actually not optional;
- the build.properties does not include some key directories or resources;
- the class files are not being bundled into a library, but the classpath does not include ".".
Tycho is not the cause of these issues, but Tycho does help "discover" these issues.
Sources of help:
- The PDE FAQ, particularly the section on Build and Deployment Errors.
- Tips on diagnosing bundle load failures.
Why do some images not get updated in the native launcher for Windows?
For Windows, the process of replacing the images in the native launcher is described below. The processing is done by p2 class: org.eclipse.pde.internal.swt.tools.IconExe
This class looks at the resources of native launcher and notes the bitmaps that are in there: their sizes and their color depth. Then it looks at the provided images. This can be a list of separate BPMs or an ICO file containing multiple BMPs. Their sizes and color depths are also noted. This only works when all provided images are uncompressed. When one or more of the images is compressed, the process stops and no bitmaps are replaced in the native launcher. Next it tries to match the provided BMP sizes and color depths to the ones in the native launcher and where they match, they are replaced in the native launcher. When one or more bitmaps in the native launcher are not available in the provided images, the following message is written to System.err:
Error - <n> icon(s) not replaced in […]using […]
The class IconExe has a main method and can be run as stand-alone. Its first argument is the native launcher that needs to be modified and the following arguments are the provided BPM or ICO files.
For Eclipse 4.3(.x), the native launcher contains 7 bitmaps:
- 256x256, 32 bit (RGB / Alpha Channel)
- 48x48, 32 bit (RGB / Alpha Channel)
- 32x32, 32 bit (RGB / Alpha Channel)
- 16x16, 32 bit (RGB / Alpha Channel)
- 48x48, 8 bit (256 colors)
- 32x32, 8 bit (256 colors)
- 16x16, 8 bit (256 colors)
So, for the process of replacing the images to be successful, 7 images with the same size and depth need to be provided, either as separate BMPs or inside an ICO.
Note: some image manipulation applications, that can create ICO files, tend to compress the 256x256x32 image by default. So be careful that all images in the ICO file are uncompressed.
Also see related stackoverflow answer by Andrew Niefer
Documentation
In Eclipse IDE
What do I need to install in my Eclipse IDE to easily work with Tycho?
In order to provide a good integration with Tycho, it's recommended that you install in your Eclipse IDE m2e (Maven support) which is often part of your default IDE, and that you install the m2e-tycho connector. From the pom editor, when opening a pom file for a module with a Tycho packaging-type such as eclipse-plugin, you should find the necessary links to install the connector if it's not already installed. Otherwise, you can go to the Window > Preferences window, find Maven/Discovery page, and click Load catalog. The Tycho lifecycle connector should be visible for installation.
When I import my project in Eclipse, the IDE tells me “Bundle X cannot be resolved.”
Currently, there is no mapping between the Tycho target-platform-configuration element as specified in pom files, and the Target-Platform in your IDE. So you need to manually make sure that your Target-Platform enabled in your IDE contains the necessary bundles and dependencies to work with your Tycho project, ideally the exact same content. The Target-Platform in Eclipse IDE can be configured in Preferences > Plug-in Development > Target Platforms.
To easily keep both Tycho and Eclipse/PDE target-platforms synchronized, it is recommended that you define a .target file and configure Tycho build and Eclipse IDE to use it for dependency resolution. See Tycho/Target_Platform#Target_files for more details.