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"

m (minor fixes)
(435313 use first EE from BREE header)
(7 intermediate revisions by one other user not shown)
Line 5: Line 5:
 
=== Execution environment configuration ===
 
=== Execution environment configuration ===
  
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 can be configured through several configuration parameters (with different precedence). The first one that is defined wins:
  
 
# The <tt>&lt;executionEnvironment&gt;</tt> parameter in <tt>target-platform-configuration/configuration</tt>
 
# The <tt>&lt;executionEnvironment&gt;</tt> parameter in <tt>target-platform-configuration/configuration</tt>
Line 11: Line 11:
 
# 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 <tt>target-platform-configuration/configuration</tt>
 
# The <tt>&lt;executionEnvironmentDefault&gt;</tt> parameter in <tt>target-platform-configuration/configuration</tt>
 +
# The global default JavaSE-1.6 (since Tycho 0.17)
  
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>.
  
 
==== Configuration via the bundle manifest ====
 
==== Configuration via the bundle manifest ====
  
Unlike the other parameters, the <tt>Bundle-RequiredExecutionEnvironment</tt> header in the MANIFEST.MF allows to specify multiple execution environments (see [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fguide%2Ftools%2Feditors%2Fmanifest_editor%2Foverview.htm 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 &lt; CDC/Foundation &lt; J2SE or JavaSE), the lowest version is selected.  
+
Unlike the other parameters, the <tt>Bundle-RequiredExecutionEnvironment</tt> header in the MANIFEST.MF allows to specify multiple execution environments (see [http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fguide%2Ftools%2Feditors%2Fmanifest_editor%2Foverview.htm here for a motivation]). <strike>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 &lt; CDC/Foundation &lt; J2SE or JavaSE), the lowest version is selected.</strike> Since Tycho 0.22.0, the execution environment listed first is used - just like in Eclipse.
  
 
=== Effects of the execution environment in the build ===
 
=== Effects of the execution environment in the build ===
Line 23: Line 24:
  
 
* 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, 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]).
+
** Limitation: For <tt>eclipse-repository</tt> modules, the dependency resolution may not be correct for execution environments other than <tt>JavaSE-1.6</tt>, <tt>JavaSE-1.7</tt>, and <tt>JavaSE-1.8</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
+
* If the source/target compliance level to be used for compilation is not configured explicitly (cf. [http://www.eclipse.org/tycho/sitedocs/tycho-compiler-plugin/compile-mojo.html tycho-compiler-plugin] documentation), the default source/target level of the execution environment is used. For the execution environments <tt>J2SE-1.5</tt>, <tt>JavaSE-1.6</tt>, <tt>JavaSE-1.7</tt>, 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 [http://git.eclipse.org/c/tycho/org.eclipse.tycho.git/tree/tycho-core/src/test/java/org/eclipse/tycho/core/ee/StandardExecutionEnvironmentTest.java#n88 here].
  
 
==== Toolchains ====
 
==== Toolchains ====
Line 37: Line 38:
 
=== Custom execution environment profiles ===
 
=== Custom execution environment profiles ===
  
TODO document new features from [https://bugs.eclipse.org/bugs/show_bug.cgi?id=385703 bug 385703]
+
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, <tt>javax.activation</tt> 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) <tt>javax.activation</tt> is provided in version <tt>0.0.0</tt>, whereas bundles providing the package (e.g. from the [http://ebr.springsource.com/ SpringSource EBR]) typically provide the package in a non-zero version. Therefore switching from J2SE-1.5 with the bundle for <tt>javax.activation</tt> 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 <tt>org.osgi.framework.system.packages</tt> in a way so that a package import of <tt>javax.activation;version="1.1.0"</tt> 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 <tt>&lt;executionEnvironment&gt;CustomProfile-1.0&lt;/executionEnvironment&gt;</tt>. Note: Custom profiles cannot be specified in the <tt>Bundle-RequiredExecutionEnvironment</tt> header.
 +
 +
The specification for the configured custom profile is then taken from the [[Tycho/Target Platform|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 <tt>eclipse-repository</tt> module, set the parameter <tt>profileFile</tt> on the <tt>tycho-p2-publisher-plugin</tt> so that it points to the execution environment file, and have the goal <tt>tycho-p2-publisher-plugin:publish-ee-profile</tt> executed. The profile file needs to be in the format commonly used by Equinox ([http://git.eclipse.org/c/equinox/rt.equinox.framework.git/tree/bundles/org.eclipse.osgi/JavaSE-1.6.profile Example]). Tycho reads the following properties from the profile file: <tt>osgi.java.profile.name</tt>, <tt>org.osgi.framework.system.packages</tt>, and <tt>org.osgi.framework.system.capabilities</tt>.
 +
 +
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.
  
 
[[Category:Tycho|Execution Environments]]
 
[[Category:Tycho|Execution Environments]]

Revision as of 12:37, 15 September 2014

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 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
  5. The global default JavaSE-1.6 (since Tycho 0.17)

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. Since Tycho 0.22.0, the execution environment listed first is used - just like in Eclipse.

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

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

Back to the top