Difference between revisions of "Tycho/Execution Environments"

Revision as of 12:50, 31 October 2012

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:

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 most restricted 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

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

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.

TODO fill in the details

Related: 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: For certain packages like javax.activation, you need an additional bundle providing the package for an J2SE-1.5 execution environment. Such a bundle is not needed for for JavaSE-1.6 because that execution environment provides the package. However the package versions differ: in JavaSE-1.6 (as defined by Equinox) javax.activation is provided in version 0.0.0, but bundles providing that package (e.g. from the SpringSource EBR) typically provide the package in a non-zero version. Therefore switching from J2SE-1.4 with the bundle for javax.activation to JavaSE-1.5 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 for example a package import of javax.activation;version="1.1.0" of a bundle is still 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 standard profiles, e.g. by configuring <executionEnvironment>CustomProfile-1.0</executionEnvironment>. Note: Custom profiles cannot be specified in the <tt>Bundle-RequiredExecutionEnvironment header.

The definition 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.

Publishing a custom execution environment

Note: Unless you are building an OSGi server, you should not be defining a custom profile. To avoid over-use, this section intentionally doesn't provide copy&paste templates.

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. TODO example