Tycho build: Purpose of target-platform-configuration's executionEnvironment attribute

[Dani-Hub]

We're using the headless tycho build following the layout described here:

https://tycho.eclipseprojects.io/doc/latest/StructuredBuild.html

Our tycho build only generates an executable (Because the target platform completely defines the content), so our target platform file just looks like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<?pde version="3.8"?>
<target name="target-platform">
    <locations>
        <location path="target/thirdparty" type="Directory"/>
    </locations>
</target>

Up to now we are using Java-17 as both execution environment and compile environment, so we are currently have the following places where we refer to the JRE:

1. The product file contains:

   <launcherArgs>
      [...]
      <vmArgs>-Dosgi.requiredJavaVersion=17 [...]
      </vmArgs>
   </launcherArgs>

   <vm>
      <windows include="false">org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-17</windows>
   </vm>

2. Our tycho-p2-director-plugin invocation:

            <plugin>
                <groupId>org.eclipse.tycho</groupId>
                <artifactId>tycho-p2-director-plugin</artifactId>
                <version>${tycho.version}</version>
                <executions>
                    <execution>
                        <id>materialize-products</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>materialize-products</goal>
                        </goals>
                        <configuration>
                            <productRepository>https://download.eclipse.org/justj/jres/17/updates/release/17.0.15</productRepository>
                        </configuration>
                    </execution>
                    <execution>
                        <id>archive-products</id>
                        <goals>
                            <goal>archive-products</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

3. Our target-platform-configuration invocation:

			<plugin>
				<groupId>org.eclipse.tycho</groupId>
				<artifactId>target-platform-configuration</artifactId>
				<version>${tycho.version}</version>
				<configuration>
					<executionEnvironment>JavaSE-17</executionEnvironment>
					<target>
						<file>../target-definition/target-platform.target</file>
					</target>
				</configuration>
			</plugin>

Now we want to switch to use still Java-17 as compile environment but Java-21 as execution environment (Very similar to the current Eclipse product seems to be build), so I adjusted all these places to refer to Java-21 instead of Java-17 (But still use Java-17 to execute the tycho build):

1. The product file contains:

   <launcherArgs>
      [...]
      <vmArgs>-Dosgi.requiredJavaVersion=21 [...]
      </vmArgs>
   </launcherArgs>

   <vm>
      <windows include="false">org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-21</windows>
   </vm>

2. Our tycho-p2-director-plugin invocation:

            <plugin>
                <groupId>org.eclipse.tycho</groupId>
                <artifactId>tycho-p2-director-plugin</artifactId>
                <version>${tycho.version}</version>
                <executions>
                    <execution>
                        <id>materialize-products</id>
                        <phase>prepare-package</phase>
                        <goals>
                            <goal>materialize-products</goal>
                        </goals>
                        <configuration>
                            <productRepository>https://download.eclipse.org/justj/jres/21/updates/release/21.0.7</productRepository>
                        </configuration>
                    </execution>
                    <execution>
                        <id>archive-products</id>
                        <goals>
                            <goal>archive-products</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>

3. Our target-platform-configuration invocation:

			<plugin>
				<groupId>org.eclipse.tycho</groupId>
				<artifactId>target-platform-configuration</artifactId>
				<version>${tycho.version}</version>
				<configuration>
					<executionEnvironment>JavaSE-21</executionEnvironment>
					<target>
						<file>../target-definition/target-platform.target</file>
					</target>
				</configuration>
			</plugin>

With these setting the tycho build fails:

[ERROR] Could not find specification for custom execution environment profile 'JavaSE-21' in the target platform

After some wondering about the error I found out that I could solve the issue by two different approaches:

a) Either I change the executionEnvironment of the target-platform-configuration execution to
<executionEnvironment>JavaSE-17</executionEnvironment> (but no other JRE setting!)

b) Or instead I use Java-21 to execute the tycho build (But no other JRE setting!).

This surprises me a bit: I would have expected that <executionEnvironment>JavaSE-21</executionEnvironment> describes the execution environment of the product (Not the compile environment), but it doesn't seem to behave that way.

Why is the build failing without one of these workarounds applied?

[laeubi]

If you want to run with Java 21, then you need a Java 21 JVM (either as build vm or in the toolchains).

[Dani-Hub]

It is not really clear to me why, since the Java VM used by the tycho build does not have any relation to the execution environment of my application, at least as I see it. Note also that the fact that I can set <executionEnvironment>JavaSE-17</executionEnvironment> to the target-platform-configuration configuration and keep all other Java-21 settings and get the wanted effect: Namely that I get a product that uses Java-21 as execution environment. It seems somehow as if the executionEnvironment attribute of the target-platform-configuration doesn't refer to my product's JRE requirements but to the tycho-build JRE requirement, is that correct?

[laeubi]

It is not really clear to me why, since the Java VM used by the tycho build does not have any relation to the execution environment of my application

You ask Tycho to resolve your target with Java 21 as the Java Runtime, without such runtime available Tycho can not do that and you get an error.

Namely that I get a product that uses Java-21 as execution environment

Please don't confuse execution environment with the JVM used to start your product, you can always start your product with whatever JVM seem suitable, but your bundle will not resolve its execution environment is not fulfilled (what currently is Java 17).

It seems somehow as if the executionEnvironment attribute of the target-platform-configuration doesn't refer to my product's JRE requirements but to the tycho-build JRE requirement, is that correct?

The product has not really an execution environment, this is effectively set by the bundles you include in your product. -Dosgi.requiredJavaVersion=17 is only relevant for P2 when updating your product and the <vm> option is only used by PDE when creating a launch config.

[merks]

I didn't follow in detail and I'm not sure which JRE you are using, but in Oomph I specify

<executionEnvironment>org.eclipse.justj.openjdk.hotspot.jre.minimal-21</executionEnvironment>

These are available:

The a.jre. is added to find the IU corresponding to the EE...

[Dani-Hub]

Thanks Ed for your reply, but when I'm using this setting, I'm getting the build error:

Could not find specification for custom execution environment profile 'org.eclipse.justj.openjdk.hotspot.jre.minimal-21' in the target platform

Again, when restoring to JavaSE-17 it succeeds again and I'm getting the correct plugin org.eclipse.justj.openjdk.hotspot.jre.full.win32.x86_64_21.0.7.v20250502-0916

[laeubi]

@Dani-Hub I don't say that @merks suggestion wont work here but it needs additional configuration and knowledge how things work internally and I won't recommend it in most of the cases.

So the most interesting question would be:

• If it works for your configuration to run with java 21 as a build JVM why do you don't want to use that?
• If it works keeping JavaSE-17 and obviously neither your plugins nor any dependencies or tests require JavaSE-21 why do you want to change it?

Without such information its very hard to further help here.

[Dani-Hub]

@laeubi I'm asking this question, because the behaviour seems non-sensical to me. There seems to exist an overloaded meaning of the term "execution environment". In my book execution environment refers to the JRE that is actually used for execution of the final product (Not the "build time" JRE), but the target-platform-configuration seems to handle it as build-time JRE.

There exists even a more confusing behaviour for another product that we build and which differs only by the here described product by the fact that we do not use the embedded JRE plugin (So we not set the includeJRE flag in the product file to true, but instead our setup program installs a JRE separately in a jre folder parallel to the executable). In this case the not fully understood "trick" to set the executionEnvironment attribute of the target-platform-configuration execution doesn't help. I'm getting in this case the following error when building with an Java-17 (instead of Java-21) JRE:

[ERROR] Failed to execute goal org.eclipse.tycho:tycho-p2-director-plugin:4.0.13:materialize-products (materialize-products) on project rcp-build: Installation of product administration-client for environment win32/win32/x86_64 failed: Call to p2 director application failed:Cannot complete the install because one or more required items could not be found.: [Software being installed: administration-client 1.0.0.202507020600; Missing requirement for filter properties ~= $0: administration-client 1.0.0.202507020600 requires 'osgi.ee; JavaSE [21.0.0,21.0.0], filter=(osgi.os=win32)' but it could not be found]. Program arguments were: [-metadataRepository, file:/[..]/de.bdal.admintool.rcp-build/products/target/,file:/[..]/de.bdal.admintool.rcp-build/products/target/targetPlatformRepository/, -artifactRepository, file:/[..]/de.bdal.admintool.rcp-build/products/target/,file:/resolution-context-artifacts@D%[..]%255Cde.bdal.admintool.rcp-build%255Cproducts,file:/D:/[..]/mvn-local-repo/, -installIU, administration-client, -destination, D:\[..]\de.bdal.admintool.rcp-build\products\target\products\administration-client\win32\win32\x86_64, -profile, DefaultProfile, -profileProperties, org.eclipse.update.install.features=true, -roaming, -p2.os, win32, -p2.ws, win32, -p2.arch, x86_64]. -> [Help 1]

(Some path elements have been obscured by [..] above). Only when building using a Java-21 VM, the build succeeds. This is a problem currently for us, because our build environments (Jenkins) are not Java-21-ready (I could perform the test only on my local machine). To solve the problem I played around and finally decided to add a p2.inf file next to the product file with this setting:

provides.0.namespace = osgi.ee
provides.0.name = JavaSE
provides.0.version = 21.0.0

This seemed to do (another) trick and allowed me to still use Java-17 for the build but getting a product that has the wanted ini file setting -Dosgi.requiredJavaVersion=21.

While I was able to make it work to me this behaviour (and the need to use an extra p2.inf configuration for this) looks surprising, in particular why the build reacts in so different ways on the executionEnvironment attribute of the target-platform-configuration. To me this smells like a bug, albeit I must say that I don't fully understand where.

[laeubi]

I'm asking this question, because the behaviour seems non-sensical to me.

Why? If you look here it says:

Force an execution environment for dependency resolution. If unset, use the default JRE of your computer.
Set to none to force the resolution to happen without any execution environment, typically when the module is supposed to use system packages coming from some dependencies (eg shipping a JRE inside products with Eclipse JustJ).

If anything is unclear, please let us know what exactly is unclear or suggest a better description.

So you define here to use JavaSE-21 for dependency resolution, but Tycho can not find such thing -> Error I must confess that this is highly expected here.

In my book execution environment refers to the JRE that is actually used for execution of the final product

I think it will of course depend on the book and how old it is and the context in what it is mentioned. "execution environment" is a generic term that can mean many things, in general in OSGi defines these here but with modular VMs the concept of "execution environment" is almost obsolete and more means "minimal java bytecode version".

In this case the not fully understood "trick" to set the executionEnvironment attribute of the target-platform-configuration execution doesn't help

This is not a "trick" ... in short, if your plugins want to use a lower BREE (e.g. 17) but your dependencies require a higher one (e.g. 21) you set it to force (as per documentation) to use a higher JVM Profile (!) than whats actually required.

I'm getting in this case the following error when building with an Java-17 (instead of Java-21) JRE:

This is because one of the plugins require Java 21, so its not really surprising, as said, defining a toolchains.xml would work as well, as adding a JVM provider like JustJ

This seemed to do (another) trick and allowed me to still use Java-17 for the build but getting a product that has the wanted ini file setting -Dosgi.requiredJavaVersion=21.

I don't really get why you want -Dosgi.requiredJavaVersion=21 at all it has no advantage if you pack a JDK with your product anyways and you should be able to set it regardless of what build JVM you use anyways.

To me this smells like a bug, albeit I must say that I don't fully understand where.

The "bug" is likely in your build configuration and setup that is completely different to how 99.9% of people build their products and want Tycho to ensure that everything works and resolves at runtime. You also have contradictory requirements by building a product that runs on Java 21 but should be build without a real Java 21 JVM, so even if p2.inf works it effective just silence the error by claiming a requirement is fulfilled that is actually not there during the build.

[merks]

Again, not reading the full details, I suggested org.eclipse.justj.openjdk.hotspot.jre.minimal-21 (because Oomph is using the minimal JRE) but noted that there are 6 different choices. It appears you would want to use org.eclipse.justj.openjdk.hotspot.jre.full-21. I.e, use the one corresponding to the JRE you are using.

This shows an example:

https://eclipse.dev/justj/?page=documentation

[Dani-Hub]

Unfortunately this does not help, I'm still getting the error

[ERROR] Could not find specification for custom execution environment profile 'org.eclipse.justj.openjdk.hotspot.jre.full-21' in the target platform

[laeubi]

@merks neither of these will work, as JustJ is not in the target nor in any repository, so Tycho can never find any of those things anyways.

[merks]

Yes, I'm making assumptions that likely don't apply. Sorry.