Jump to: navigation, search

Difference between revisions of "Tycho/FAQ"

(redirect target platform question to new page)
(deleted product-FAQ completely because the problem making it a FAQ has been resolved)
(46 intermediate revisions by 11 users not shown)
Line 1: Line 1:
 +
See also the [http://stackoverflow.com/questions/tagged/tycho?sort=faq Frequently asked Tycho questions on stackoverflow.com].
 +
 +
= Compilation =
 +
 +
== How do I embed a configurable build version? ==
 +
 +
To cause your artifacts to be branded with the a build number, modify your manifests (<tt>MANIFEST.MF</tt>, <tt>feature.xml</tt>, etc.) to specify the version as <tt><em>X.Y.Z</em>.qualifier</tt>, and the corresponding <tt>pom.xml</tt> with <tt>X.Y.Z-SNAPSHOT</tt>.  Tycho will replace the <tt>qualifier</tt> and <em>SNAPSHOT</em> with the build timestamp (in UTC).
 +
 +
You can set the build qualifier to a custom value by setting the <tt>forceContextQualifier</tt> property.  For example:
 +
<pre>mvn -DforceContextQualifier=M01 install</pre>
 +
You can also set the qualifier by configuring the tycho-packaging-plugin, using some format supported by Java's SimpleDateFormat:
 +
<source lang="xml">
 +
<plugin>
 +
  <groupId>org.eclipse.tycho</groupId>
 +
  <artifactId>tycho-packaging-plugin</artifactId>
 +
  <version>${tycho-version}</version>
 +
  <configuration>
 +
    <format>'myprefix_'yyyyMMddHHmm</format>
 +
  </configuration>
 +
</plugin>
 +
</source>
 +
 +
Tycho does not directly support embedding the build identifier in resources.  But some workarounds have been suggested in an [http://dev.eclipse.org/mhonarc/lists/tycho-user/msg01115.html email thread on tycho-user].
 +
 +
== How to configure warning/error settings of the OSGi compiler? ==
 +
 +
To configure warnings:
 +
 +
<source lang="xml">
 +
<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>
 +
</source>
 +
 +
The available warning tokens are listed in the [http://help.eclipse.org/indigo/topic/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm 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:
 +
<source lang="xml">
 +
<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>
 +
</source>
 +
 +
== How to compile pre-processed source placed in a different directory? ==
 +
 +
Configure your pom.xml with something like the following:
 +
<pre>
 +
<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>
 +
</pre>
 +
 +
== How do I include rootfiles? ==
 +
 +
Tycho provides partial support for [http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.pde.doc.user/tasks/pde_rootfiles.htm PDE-style rootfiles]. Rootfiles are associated and installed with a feature. See [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-its/projects/TYCHO465RootFiles the TYCHO465RootFiles 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 [http://kaikreuzer.blogspot.com/2010/12/building-p2-enabled-products-with-tycho.html].
 +
 +
== 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:
 +
 +
<tt>mvn help:describe -Dplugin=org.eclipse.tycho:tycho-compiler-plugin -Ddetail</tt>
 +
 +
Or you can have a look at the [http://eclipse.org/tycho/sitedocs/index.html 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 <code>tycho-compiler-jdt</code> 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 [[JDT_Core/Null_Analysis|annotation-based null analysis]] can be integrated into the build in this way.
 +
 +
Use the following snippet in your <code>build.pluginManagement.plugins</code> section:
 +
<!-- cannot use source tag, because the source end-tag inside the snippet would terminate the environment, geshi r50696  fixed this by introducing an alternative tag syntaxhighlight-->
 +
<pre lang="xml">
 +
<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 -->
 +
</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>
 +
</pre>
 +
 +
Again, a <code>build.plugins.plugin.configuration.compilerArguments.properties</code> element can be used to reference an existing <code>org.eclipse.jdt.core.prefs</code> file (see [[Tycho/FAQ#How_to_configure_warning.2Ferror_settings_of_the_OSGi_compiler.3F|above]]).
 +
 +
= Packaging =
 +
 +
== How to generate Eclipse-SourceReferences MANIFEST header? ==
 +
 +
 +
See [http://eclipse.org/tycho/sitedocs/tycho-packaging-plugin/package-plugin-mojo.html#sourceReferences docs]. Example for git:
 +
 +
<pre>
 +
<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>
 +
</pre>
 +
 +
This will add the Eclipse-SourceReferences header including commit ID used for this build and tag (if present).
 +
 +
= Testing =
 +
 
== How to configure HTTP proxy settings during test execution? ==
 
== How to configure HTTP proxy settings during test execution? ==
  
Line 71: Line 230:
 
         <useUIHarness>true</useUIHarness>
 
         <useUIHarness>true</useUIHarness>
 
         <useUIThread>false</useUIThread>
 
         <useUIThread>false</useUIThread>
 +
        <argLine>-Xms40m -Xmx512m</argLine>
 
       </configuration>
 
       </configuration>
 
     </plugin>
 
     </plugin>
 
   </plugins>
 
   </plugins>
 
</build>
 
</build>
</source>  
+
</source>
  
== How to configure warning/error settings of the OSGi compiler? ==
+
<tt>useUIHarness=true</tt> ensures the workbench is started before the tests are run.  If your app requires a custom application class (<em>viz</em> the <tt>org.eclipse.core.runtime.applications</tt> extension point), you will likely need to [[Tycho/Reference Card#Running_an_application_or_a_product | configure the application]].
  
To configure warnings:
+
You may wish to add <tt>--launcher.suppressErrors</tt> to the <tt>&lt;appArgLine&gt;</tt> element to suppress Eclipse error dialogs.
  
<source lang="xml">
+
== How do I add OS-specific flags? ==
<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>
+
</source>
+
 
+
The available warning tokens are listed in the [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.jdt.doc.isv/guide/jdt_api_compile.htm Eclipse help]. Same applies for the
+
 
+
-err
+
 
+
argument for configuring errors.
+
 
+
== How to build plugin-based products with platform-specific fragments? ==
+
 
+
First you need to configure all os/ws/arch environments for which you want to build. Example POM snippet:
+
  
 +
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:
 
<source lang="xml">
 
<source lang="xml">
<plugin>
+
   <properties>
   <groupId>org.eclipse.tycho</groupId>
+
    <os-jvm-flags/> <!-- for the default case -->
  <artifactId>target-platform-configuration</artifactId>
+
   </properties>
  <version>${tycho-version}</version>
+
   <configuration>
+
   <build>
   <resolver>p2</resolver>
+
     <plugins>
     <environments>
+
       <plugin>
       <environment>
+
         <groupId>org.eclipse.tycho</groupId>
         <os>win32</os>
+
         <artifactId>tycho-surefire-plugin</artifactId>
         <ws>win32</ws>
+
         <version>${tycho-version}</version>
         <arch>x86</arch>
+
        <configuration>
      </environment>
+
          <useUIHarness>false</useUIHarness>
      <environment>
+
          <useUIThread>true</useUIThread>
        <os>win32</os>
+
          <argLine>-Xms40m -Xmx1G ${os-jvm-flags}</argLine>
        <ws>win32</ws>
+
         </configuration>
         <arch>x86_64</arch>
+
       </plugin>
       </environment>
+
     </plugins>
     </environments>
+
   </build>
   </configuration>
+
</plugin>
+
</source>  
+
  
for plugin-based (as opposed to feature-based) .product files, tycho needs additional os/ws/arch attributes for the fragments in the .product file which are not required by PDE.  
+
  <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>
 +
</source>
 +
Alternatively you could configure the surefire plugins within a profile too.
  
Example product file snippet:
+
== How to add a undeclared dependency?  (e.g., OSGi declarative service) ==
  
<source lang="xml">
+
Use the <tt> tycho-surefire-plugin</tt> <tt>&lt;dependencies&gt;</tt> section (see the [[Tycho/Packaging_Types#eclipse-test-plugin | eclipse-test-plugin]] packaging type for an example).
<plugin id="org.eclipse.swt.win32.win32.x86" fragment="true" os="win32" ws="win32" arch="x86"/>
+
<plugin id="org.eclipse.swt.win32.win32.x86_64" fragment="true" os="win32" ws="win32" arch="x86_64"/>
+
</source>  
+
  
 
== How to test OSGi declarative services? ==
 
== How to test OSGi declarative services? ==
Line 151: Line 299:
 
   </configuration>
 
   </configuration>
 
</plugin>
 
</plugin>
</source>  
+
</source>
  
== How do I include rootfiles? ==
 
  
Tycho provides partial support for [http://help.eclipse.org/indigo/index.jsp?topic=/org.eclipse.pde.doc.user/tasks/pde_rootfiles.htm PDE-style rootfiles]. Rootfiles are associated and installed with a feature. See [https://github.com/sonatype/sonatype-tycho/tree/master/tycho-its/projects/TYCHO465RootFiles the TYCHO465RootFiles test] for an example of using rootfiles.
+
== How do I enable assertions during testing? ==
  
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 [http://kaikreuzer.blogspot.com/2010/12/building-p2-enabled-products-with-tycho.html].
+
Add an &lt;argLine&gt; to the <tt>tycho-surefire-plugin</tt>'s configuration:
 +
<source lang="xml">
 +
<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>
 +
</source>
  
== How should I define the target platform of my tycho project? ==
 
  
This question is answered here: [[Tycho/Target Platform]]
+
== How can I debug my tests? ==
 +
 
 +
Add <tt>-DdebugPort=8000</tt> to your Maven commandline and attach a remote debug session.
 +
 
 +
See the docs http://www.eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html#debugPort
 +
 
 +
= Diagnosing Build Problems =
 +
 
 +
== What does Tycho's message "XXXX" mean? ==
 +
 
 +
See the [[Tycho_Messages_Explained | Tycho Messages Explained]] page.
 +
 
  
 
== My build fails with a ClassCastException of a Tycho class. What is wrong? ==
 
== My build fails with a ClassCastException of a Tycho class. What is wrong? ==
Line 168: Line 341:
 
The problem typically occurs if some of the modules use the incorrect parent POM, e.g. an older version of the correct parent. Check the parent configuration in all modules of the reactor.
 
The problem typically occurs if some of the modules use the incorrect parent POM, e.g. an older version of the correct parent. Check the parent configuration in all modules of the reactor.
  
[[Category:Tycho|FAQ]]
+
== How to switch on eclipse tracing during test execution? ==
 +
 
 +
Eclipse has a [http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fguide%2Ftools%2Flaunchers%2Ftracing.htm 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 inte the test project root.
 +
 
 +
E.g. a file .options with content
 +
 
 +
<pre>
 +
org.eclipse.osgi/resolver/debug=true
 +
org.eclipse.osgi/resolver/wiring=true
 +
</pre>
 +
 
 +
will switch on equinox wiring tracing.
 +
 
 +
== 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 <tt>ClassNotFoundException</tt> and <tt>NoClassDefFoundError</tt> 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 <tt>build.properties</tt> 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 | PDE FAQ]], particularly the section on [[PDE/FAQ#Build_and_Deployment_Errors | Build and Deployment Errors]].
 +
* [[Where_Is_My_Bundle | Tips on diagnosing bundle load failures]].
 +
 
 +
== How do I disable P2 mirrors? ==
 +
 
 +
Often times eclipse.org redirects P2 repository requests to a misconfigured/broken/unavailable P2 mirror repository and builds fail because of that. To disable use of P2 mirrors and force all downloads to go directly to the main repository specify the following maven command line parameter
 +
 
 +
<pre>
 +
-Dtycho.disableP2Mirrors=true
 +
</pre>
 +
 
 +
= Documentation =
 +
 
 +
== Where can I find the Maven generated documentation for the Tycho plug-ins? ==
 +
 
 +
The documentation is available at:
 +
 
 +
http://www.eclipse.org/tycho/sitedocs/
 +
 
 +
and
 +
 
 +
http://www.eclipse.org/tycho/sitedocs-extras/
 +
 
 +
For more info see [[Tycho/Reference_Plugin_Docs]].
 +
 
 +
[[Category:Tycho|FAQ]][[Category:FAQ]]

Revision as of 05:50, 18 March 2013

See also the Frequently asked Tycho questions on stackoverflow.com.

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:

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

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>

How do I include rootfiles?

Tycho provides partial support for PDE-style rootfiles. Rootfiles are associated and installed with a feature. See the TYCHO465RootFiles 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 [1].

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 -->
	</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).

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

Testing

How to configure HTTP proxy settings during test execution?

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

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>


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 to test OSGi declarative services?

You need to add bundle org.eclipse.equinox.ds to the test runtime:

<plugin>
  <groupId>org.eclipse.tycho</groupId>
  <artifactId>tycho-surefire-plugin</artifactId>
  <configuration>
    <dependencies>
      <dependency>
        <type>p2-installable-unit</type>
        <artifactId>org.eclipse.equinox.ds</artifactId>
      </dependency>
    </dependencies>
  </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 http://www.eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html#debugPort

Diagnosing Build Problems

What does Tycho's message "XXXX" mean?

See the Tycho Messages Explained page.


My build fails with a ClassCastException of a Tycho class. What is wrong?

ClassCastExceptions 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. Check the parent configuration in all modules of the reactor.

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

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:

How do I disable P2 mirrors?

Often times eclipse.org redirects P2 repository requests to a misconfigured/broken/unavailable P2 mirror repository and builds fail because of that. To disable use of P2 mirrors and force all downloads to go directly to the main repository specify the following maven command line parameter

-Dtycho.disableP2Mirrors=true

Documentation

Where can I find the Maven generated documentation for the Tycho plug-ins?

The documentation is available at:

http://www.eclipse.org/tycho/sitedocs/

and

http://www.eclipse.org/tycho/sitedocs-extras/

For more info see Tycho/Reference_Plugin_Docs.