Re-examine version check when cross linking

XMLWordPrintable

    • Type: CSR
    • Resolution: Unresolved
    • Priority: P3
    • 26
    • Component/s: tools
    • None
    • behavioral
    • medium
    • Hide
      We know that some developers/customers use jlink for cross-linking, it's a useful feature. A possible scenario is a CI system running on linux-x64 where part of the build produces run-time images for windows-x64 or other platforms.

      The stricter change proposed in this CSR will have no impact on environments that keep their JDK and the package modules for the target platform in sync. If running jlink on JDK X.0.N from vendor Z, and the packaged modules for the target platform are also JDK X.0.N from vendor Z, then it will work as before.

      The compatibility issue is when developers/customers are mixing builds from different vendors, or assuming that jlink on JDK X.0.N can reliably produce a run-time image for JDK X.0.M, where $N and $M are different.

      So low-to-medium risk change.
      Show
      We know that some developers/customers use jlink for cross-linking, it's a useful feature. A possible scenario is a CI system running on linux-x64 where part of the build produces run-time images for windows-x64 or other platforms. The stricter change proposed in this CSR will have no impact on environments that keep their JDK and the package modules for the target platform in sync. If running jlink on JDK X.0.N from vendor Z, and the packaged modules for the target platform are also JDK X.0.N from vendor Z, then it will work as before. The compatibility issue is when developers/customers are mixing builds from different vendors, or assuming that jlink on JDK X.0.N can reliably produce a run-time image for JDK X.0.M, where $N and $M are different. So low-to-medium risk change.
    • File or wire format, Other
    • JDK

      Summary

      The jlink tool provides a means to generate a JDK run-time image that contains only the required modules. The tool is tightly coupled to the java.base module on expected behavior. For example, how modules included in the image are to be validated. Therefore, the jlink tool should verify that the java.base module included in the target image is compatible with the java.base module used by jlink.

      Problem

      At this time the version check fails if the java.base module isn't the same feature and interim version as 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 a change to something 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. This approach allows the build of JDK to generate a signature for compatible runtime.

      Specification

      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 release.txt file is being generated at JDK build time. In the OpenJDK, the current content would be a line composed of $IMPLEMENTOR-$JAVA_RUNTIME_VERSION-$JAVA_VERSION_DATE as values exist in the release file. For example, Oracle Corporation-25.0.1+8-LTS-27-2025-10-21.

      Following scenario can be happening 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'.

            Assignee:
            Henry Jen
            Reporter:
            Alan Bateman
            Votes:
            0 Vote for this issue
            Watchers:
            4 Start watching this issue

              Created:
              Updated: