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 is determined through the following configuration parameters, in decreasing order of precedence:
- The <executionEnvironment> parameter in target-platform-configuration/configuration
- The jre.compilation.profile property in the build.properties (eclipse-plugin and eclipse-test-plugin modules only)
- The most restricted profile specified in the Bundle-RequiredExecutionEnvironment header (see details below; eclipse-plugin and eclipse-test-plugin modules only)
- The <executionEnvironmentDefault> parameter in target-platform-configuration/configuration
You can specify the commonly known execution environments, for example "J2SE-1.5" (!), "JavaSE-1.6", "JavaSE-1.7", 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). If this is the case, Tycho picks 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 and JavaSE-1.7 (bug 385703).
- 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).
- TODO describe effect on compiler source & target levels
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.
TODO fill in the details
Custom execution environment profiles
TODO document new features from bug 385703