Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Tycho/Execution Environments"

(where to configure parameters in target-platform-configuration doesn't seem to be obvious; maybe we should also link to an example)
m (minor fixes)
Line 1: Line 1:
An execution environment profile describes the capabilities of a Java runtime environment (JRE). In order to build for 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.
+
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 <tt>java.*</tt> packages, so you can't specify through a package import that, for example, your bundle needs <tt>java.lang</tt> in a version that contains the <tt>Enum</tt> class. Instead, there is the possibility to specify a requirement on the execution environment, e.g. <tt>Bundle-RequiredExecutionEnvironment: J2SE-1.5</tt>.
 
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 <tt>java.*</tt> packages, so you can't specify through a package import that, for example, your bundle needs <tt>java.lang</tt> in a version that contains the <tt>Enum</tt> class. Instead, there is the possibility to specify a requirement on the execution environment, e.g. <tt>Bundle-RequiredExecutionEnvironment: J2SE-1.5</tt>.
Line 7: Line 7:
 
The execution environment profile for the build is determined through the following configuration parameters, in decreasing order of precedence:
 
The execution environment profile for the build is determined through the following configuration parameters, in decreasing order of precedence:
  
# The <tt>&lt;executionEnvironment&gt;</tt> parameter in the <tt>target-platform-configuration/configuration</tt>
+
# The <tt>&lt;executionEnvironment&gt;</tt> parameter in <tt>target-platform-configuration/configuration</tt>
 
# The <tt>jre.compilation.profile</tt> property in the build.properties (<tt>eclipse-plugin</tt> and <tt>eclipse-test-plugin</tt> modules only)
 
# The <tt>jre.compilation.profile</tt> property in the build.properties (<tt>eclipse-plugin</tt> and <tt>eclipse-test-plugin</tt> modules only)
 
# The most restricted profile specified in the <tt>Bundle-RequiredExecutionEnvironment</tt> header (see details below; <tt>eclipse-plugin</tt> and <tt>eclipse-test-plugin</tt> modules only)
 
# The most restricted profile specified in the <tt>Bundle-RequiredExecutionEnvironment</tt> header (see details below; <tt>eclipse-plugin</tt> and <tt>eclipse-test-plugin</tt> modules only)
# The <tt>&lt;executionEnvironmentDefault&gt;</tt> parameter in the <tt>target-platform-configuration/configuration</tt>
+
# The <tt>&lt;executionEnvironmentDefault&gt;</tt> parameter in <tt>target-platform-configuration/configuration</tt>
  
 
You can specify the commonly known execution environments, for example "<tt>J2SE-1.5</tt>" (!), "<tt>JavaSE-1.6</tt>", "<tt>JavaSE-1.7</tt>", or "<tt>OSGi/Minimum-1.2</tt>".
 
You can specify the commonly known execution environments, for example "<tt>J2SE-1.5</tt>" (!), "<tt>JavaSE-1.6</tt>", "<tt>JavaSE-1.7</tt>", or "<tt>OSGi/Minimum-1.2</tt>".
Line 23: Line 23:
  
 
* During dependency resolution (and similarly for target definition files with <tt>includeMode="planner"</tt>), 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 <tt>javax.xml</tt> and the execution environment is <tt>J2SE-1.4</tt>, Tycho will attempt to download and use a dedicated bundle providing <tt>javax.xml</tt>; if the execution environment was <tt>J2SE-1.5</tt>, the <tt>javax.xml</tt> package provided by the JRE would be used. (The package <tt>javax.xml</tt> was added in Java 5.)
 
* During dependency resolution (and similarly for target definition files with <tt>includeMode="planner"</tt>), 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 <tt>javax.xml</tt> and the execution environment is <tt>J2SE-1.4</tt>, Tycho will attempt to download and use a dedicated bundle providing <tt>javax.xml</tt>; if the execution environment was <tt>J2SE-1.5</tt>, the <tt>javax.xml</tt> package provided by the JRE would be used. (The package <tt>javax.xml</tt> was added in Java 5.)
** Limitation: For <tt>eclipse-repository</tt> modules and execution environments other than <tt>JavaSE-1.6</tt> and <tt>JavaSE-1.7</tt>, the dependency resolution may not be correct ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=385703 bug 385703]).
+
** Limitation: For <tt>eclipse-repository</tt> modules, the dependency resolution may not be correct for execution environments other than <tt>JavaSE-1.6</tt> and <tt>JavaSE-1.7</tt> ([https://bugs.eclipse.org/bugs/show_bug.cgi?id=385703 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).
 
* 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
 
* TODO describe effect on compiler source & target levels

Revision as of 07:53, 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

TODO document new features from bug 385703

Back to the top