Tycho/Execution Environments

This is obsolete since Tycho 2.0, documentation about target-platfroms and execution environments is moving to https://www.eclipse.org/tycho/sitedocs/target-platform-configuration/target-platform-configuration-mojo.html

An execution environment profile describes the capabilities of a Java runtime environment (JRE). In order to build for a certain minimal JRE version, e.g. for Java SE 5 and later, Tycho allows you to select the execution environment profile to be used in the build.

Background: In OSGi, you can express that you need a certain minimum version of a library by importing a package from the library with a lower bound on the version. For the JRE itself, this approach is not possible: bundles don't specify imports on java.* packages, so you can't specify through a package import that, for example, your bundle needs java.lang in a version that contains the Enum class. Instead, there is the possibility to specify a requirement on the execution environment, e.g. Bundle-RequiredExecutionEnvironment: J2SE-1.5.

Execution environment configuration

The execution environment profile for the build can be configured through several configuration parameters (with different precedence). The first one that is defined wins:

1. The <executionEnvironment> parameter in target-platform-configuration/configuration
2. The jre.compilation.profile property in the build.properties (eclipse-plugin and eclipse-test-plugin modules only)
3. The first profile specified in the Bundle-RequiredExecutionEnvironment header (see details below; eclipse-plugin and eclipse-test-plugin modules only)
4. The <executionEnvironmentDefault> parameter in target-platform-configuration/configuration
5. The global default JavaSE-9 (since Tycho 1.2) 1.7 (Tycho 0.23 to 1.1) JavaSE-1.6 (Tycho 0.17 to 0.22)

You can specify the commonly known execution environments, for example J2SE-1.5 (!), JavaSE-1.6, JavaSE-1.7, JavaSE-1.8, JavaSE-9, or OSGi/Minimum-1.2.

Configuration via the bundle manifest

Unlike the other parameters, the Bundle-RequiredExecutionEnvironment header in the MANIFEST.MF allows to specify multiple execution environments (see here for a motivation). Since Tycho 0.22.0, the execution environment listed first is used - just like in Eclipse. Before Tycho 0.22.0, Tycho picked the most restricted execution environment according to the following heuristic: From the most restrictive class (with OSGi/Minimum < CDC/Foundation < J2SE or JavaSE), the lowest version is selected.

Effects of the execution environment in the build

The execution environment determined according to the rules above is then used in the following aspects of the build:

• During dependency resolution (and similarly for target definition files with includeMode="planner"), Tycho ensures that package imports may only be matched against the selected execution environment, and not against other execution environments. This means that Tycho handles the following situation correctly: if your bundle requires the package javax.xml and the execution environment is J2SE-1.4, Tycho will attempt to download and use a dedicated bundle providing javax.xml; if the execution environment was J2SE-1.5, the javax.xml package provided by the JRE would be used. (The package javax.xml was added in Java 5.)
  • Limitation: For eclipse-repository modules, the dependency resolution may not be correct for execution environments other than JavaSE-1.6, JavaSE-1.7, and JavaSE-1.8 (bug 385703).
  • The restriction on the configured execution environment can be disabled for the dependency resolution by setting the target-platform-configuration parameter resolveWithExecutionEnvironmentConstraints to false (since Tycho 0.22.0).
• During compilation, Tycho hides packages which are not provided by the configured execution environment. Note: This filtering only applies to entire packages, and therefore may not detect the use of classes or methods which are not available in the configured execution environment. To also detect these situations, either run the build with a JDK matching the configured execution environment, or configure toolchains (see below).
• If the source/target compliance level to be used for compilation is not configured explicitly (cf. tycho-compiler-plugin documentation), the default source/target level of the execution environment is used. For the execution environments J2SE-1.5, JavaSE-1.6, JavaSE-1.7, the source and target levels are (as expected) 1.5, 1.6, respectively 1.7. For other execution environments, the default source/target level can be found here.

Toolchains

By default, Tycho compiles against the JDK that is used to run the Maven/Tycho build. Toolchains allows to configure additional JDKs, so that the build can automatically pick the correct one for the configured execution environment.

See http://www.eclipse.org/tycho/sitedocs/tycho-compiler-plugin/compile-mojo.html#useJDK

Custom execution environment profiles

In order to support special compatibility requirements of OSGi servers, Tycho has basic support for building for non-standard execution environment profiles.

Background: Certain Java packages had been developed for a while before they were eventually added to the JRE. For example, javax.activation is available in the JavaSE-1.6 execution environment, but you'll need a separate bundle that provides the package if you are building for J2SE-1.5. Unfortunately, these set-ups are not completely interchangeable: in JavaSE-1.6 (as defined by Equinox) javax.activation is provided in version 0.0.0, whereas bundles providing the package (e.g. from the SpringSource EBR) typically provide the package in a non-zero version. Therefore switching from J2SE-1.5 with the bundle for javax.activation to JavaSE-1.6 without the bundle is not a compatible change for an OSGi server. To mitigate this, the OSGi server may set the system property org.osgi.framework.system.packages in a way so that a package import of javax.activation;version="1.1.0" is wired to the system bundle. In order to get analogous effect in the build (i.e. during dependency resolution, compilation, and test execution), projects building for that OSGi server may select a special execution environment defined by the OSGi server project.

Configuring a custom execution environment

You can select a custom execution environment for the build in the same way as you select a standard execution environment, e.g. by configuring <executionEnvironment>CustomProfile-1.0</executionEnvironment>. Note: Custom profiles cannot be specified in the Bundle-RequiredExecutionEnvironment header.

The specification for the configured custom profile is then taken from the target platform, i.e. one of the configured p2 repositories must contain the custom profile specification.

Publishing a custom execution environment specification

Note: Unless you are building an OSGi server, you should not be defining a custom profile.

In an eclipse-repository module, set the parameter profileFile on the tycho-p2-publisher-plugin so that it points to the execution environment file, and have the goal tycho-p2-publisher-plugin:publish-ee-profile executed. The profile file needs to be in the format commonly used by Equinox (Example). Tycho reads the following properties from the profile file: osgi.java.profile.name, org.osgi.framework.system.packages, and org.osgi.framework.system.capabilities.

Note: In general, it should be rarely necessary to publish a new version of a custom execution environment profile. Therefore, these profiles should be released independently from the other artifacts produced by the OSGi server project. Due to technical limitations, it is not possible to build a p2 repository with just the custom execution environment profile. You will also need to add one (typically empty) feature to the repository via a category.xml.