Summary

Change the jlink tool to do strict version checking when "cross linking". Cross linking is the term we use here to describe the scenario where jlink is used to assemble a set of modules (and their dependencies) into a custom runtime image for a different OS, architecture or JDK version to the JDK containing the jlink tool.

Problem

The jlink tool assembles a set of modules and their dependencies into a custom runtime image. The process to generate the image involves the execution of a sequence of plugins that transform and optimize the classes and resources that go into the image. A number of "core" plugins are deeply tied to java.base internals, and the internals of other modules. This deep tie is problematic when using jlink to create a run-time image with modules for a different JDK build, where different JDK build means a different JDK release to the current platform, or a JDK for a different OS or architecture. If jlink and the plugins execute with a different JDK release to the target image then there is no guarantee that the resulting run-time image is usable.

At this time, jlink does a simple version check. The version check fails if the java.base module on the module path doesn't match the feature and interim version of the JDK running jlink. This check is sufficient to prevent jlink running on one feature release from creating a run-time image for a different feature release. It doesn't prevent using jlink on say JDK N.0.1 and using it to produce a run-time image for JDK N.0.2. This case will work until there is an incompatible change in java.base, or the jlink tool, that breaks this cross linking combination. The other scenario - that is more brittle - is running jlink on JDK N.0.1 from vendor X and attempting it to create a JDK N.0.1 with modules from vendor Y. If the two builds aren't from the exact same bits then there is no guarantee that it will produce a working JDK.

Solution

At build time, generate a release signature specific to the build of the JDK and embed it into the java.base module. When running jlink, this build signature will be matched with the java.base module of the target image. Generating the release signature file at build time ensures a compatible match between java.base used by jlink and the java.base version added to the target run-time.

The build process is enhanced to generate a release.txt file, which contains the build signature. That file is being included in the java.base module as a resource at jdk/internal/misc/resources/release.txt. The signature will be verified for compatibility before jlink is trying to link a different java.base module from the one used by jlink itself.

The content of the release.txt file is a single line composed of $IMPLEMENTOR-$JAVA_RUNTIME_VERSION-$JAVA_VERSION_DATE. All three values would be the same as written into the release file in the top level directory of a JDK image. For example the content of a release.txt file could be:

Oracle Corporation-25.0.1+8-LTS-27-2025-10-21

The following scenarios can happen after the proposed change:

Scenario 1 - jlink link with a java.base module has the same signature

The link process should success without any message.

$ jlink --module-path ./build/linux-x86_64-server-release/images/jdk/jmods --add-modules java.base --output linux
$ jlink --add-modules java.base --output macos

Scenario 2 - jlink link with an earlier build not containing the release.txt in the java.base module

The jlink will display an error message and failed.

$ jlink --module-path ~/linux/jdk-25.0.1/jmods --add-modules java.base --output linux25
Error: jlink build 'Oracle Corporation-26-internal-2026-03-17' cannot find the build signature in java.base specified on module path, likely from an earlier build.

Scenario 3 - jlink link with a java.base module has a different signature

The jlink will display an error message and failed.

$ jlink --module-path ~/linux/jdk-25.0.1/jmods --add-modules java.base --output linux25
Error: jlink build 'Oracle Corporation-26-internal-2026-03-17' does not match target java.base build 'N/A-26-internal-2026-03-17'.

Specification

There are no specification changes but we may update the jlink man page or docs to include a section on cross-linking and its limitations.