[GR-42402] Refine support for javaPreviewNeeded.

PullRequest: mx/1529

Author: dougxc

README.md

@@ -595,3 +595,19 @@ In other words, there should be no back-and-forth to the same repo.
 Java projects may use language or runtime features which are considered _preview features_ in certain Java versions, in which case preview features must be enabled for compilation (`--enable-preview`).
 This is specified using the `javaPreviewNeeded` attribute, which is a version specification in the same format as `javaCompliance`, for example: `"javaPreviewNeeded": "19..20"`
 If the compiling JDK matches that version or version range, preview features are enabled for compilation.
+Given that javac and the JVM must be on the same JDK version for preview features (see [here](https://nipafx.dev/enable-preview-language-features/#same-version-for-feature-compiler-and-jvm) for details),
+compiling a project with preview features will force the javac `-source` and `-target` options to `N` where `N` is
+the minimum of:
+* the version of the JDK being used for compilation (i.e. `JAVA_HOME`) and
+* the lowest version where `--enable-preview` is not needed.
+
+The following table of examples should make this clearer:
+
+| JDK | javaPreviewNeeded | -target / -source | --enable-preview |
+| ----|-------------------|-------------------|------------------|
+| 19  | 19+               | 19                | Yes              |
+| 20  | 19+               | 20                | Yes              |
+| 20  | 19                | 20                | No               |
+| 21  | 19                | 20                | No               |
+| 22  | 20                | 21                | No               |
+| 22  | 19..20            | 21                | No               |

mx.py

@@ -6920,10 +6920,15 @@ def __init__(self, suite, name, subDir, srcDirs, deps, javaCompliance, workingSe
         Project.__init__(self, suite, name, subDir, srcDirs, deps, workingSets, d, theLicense, testProject=testProject, **kwArgs)
         ClasspathDependency.__init__(self, **kwArgs)
         if javaCompliance is None:
-            abort('javaCompliance property required for Java project ' + name)
+            self.abort('javaCompliance property required for Java project')
         self.javaCompliance = JavaCompliance(javaCompliance, context=self)
         javaPreviewNeeded = kwArgs.get('javaPreviewNeeded')
-        self.javaPreviewNeeded = JavaCompliance(javaPreviewNeeded, context=self) if javaPreviewNeeded else None
+        if javaPreviewNeeded:
+            self.javaPreviewNeeded = JavaCompliance(javaPreviewNeeded, context=self)
+            if self.javaPreviewNeeded.value > self.javaCompliance.value:
+                self.abort(f'javaCompliance ({self.javaCompliance}) cannot be lower than javaPreviewNeeded ({self.javaPreviewNeeded})')
+        else:
+            self.javaPreviewNeeded = None
         # The annotation processors defined by this project
         self.definedAnnotationProcessors = None
         self.declaredAnnotationProcessors = []
@@ -7786,6 +7791,28 @@ def __init__(self, jdk, extraJavacArgs):
         self.jdk = jdk
         self.extraJavacArgs = extraJavacArgs if extraJavacArgs else []
 
+    @staticmethod
+    def get_release_args(jdk_compliance, compliance, javaPreviewNeeded):
+        """
+        Gets ``-target``, ``-source`` and ``--enable-preview`` javac arguments based on
+        `jdk_compliance`, `compliance` and `javaPreviewNeeded`.
+        """
+        enable_preview = []
+        if javaPreviewNeeded:
+            if javaPreviewNeeded._high_bound():
+                out_of_preview = javaPreviewNeeded.highest_specified_value() + 1
+                if jdk_compliance.value >= out_of_preview:
+                    c = str(out_of_preview)
+                else:
+                    c = str(jdk_compliance.value)
+                    enable_preview = ['--enable-preview']
+            else:
+                c = str(jdk_compliance)
+                enable_preview = ['--enable-preview']
+        else:
+            c = str(compliance)
+        return ['-target', c, '-source', c] + enable_preview
+
     def prepare(self, sourceFiles, project, outputDir, classPath, processorPath, sourceGenDir, jnigenDir,
         disableApiRestrictions, warningsAsErrors, forceDeprecationAsWarning, showTasks, postCompileActions):
         javacArgs = ['-g', '-d', outputDir]
@@ -7803,10 +7830,8 @@ def prepare(self, sourceFiles, project, outputDir, classPath, processorPath, sou
             javacArgs += ['-processorpath', processorPath, '-s', sourceGenDir]
         else:
             javacArgs += ['-proc:none']
-        c = str(compliance)
-        javacArgs += ['-target', c, '-source', c]
-        if project.javaPreviewNeeded and self.jdk.javaCompliance in project.javaPreviewNeeded:
-            javacArgs.append('--enable-preview')
+
+        javacArgs += JavacLikeCompiler.get_release_args(self.jdk.javaCompliance, compliance, project.javaPreviewNeeded)
         if _opts.very_verbose:
             javacArgs.append('-verbose')
 
@@ -18303,7 +18328,7 @@ def alarm_handler(signum, frame):
         abort(1, killsig=signal.SIGINT)
 
 # The version must be updated for every PR (checked in CI)
-version = VersionSpec("6.12.1") # [GR-41841] Update all digests to sha-512.
+version = VersionSpec("6.12.2") # GR-42402 - Refine support for javaPreviewNeeded.
 
 currentUmask = None
 _mx_start_datetime = datetime.utcnow()

mx_gate.py

@@ -41,6 +41,7 @@
 import mx_javacompliance
 import sys
 from mx_urlrewrites import rewriteurl
+from mx_javacompliance import JavaCompliance
 from collections import OrderedDict
 
 """
@@ -514,6 +515,24 @@ def _run_mx_suite_tests():
     """
     mx_javacompliance._test()
 
+    # (JDK, project_compliance, javaPreviewNeeded) -> expected javac args
+    get_release_args_data = {
+        (19, '19+', None):     ['-target', '19', '-source', '19'],
+        (20, '19+', None):     ['-target', '19', '-source', '19'],
+        (19, '19+', '19+'):    ['-target', '19', '-source', '19', '--enable-preview'],
+        (20, '19+', '19+'):    ['-target', '20', '-source', '20', '--enable-preview'],
+        (20, '19+', '19'):     ['-target', '20', '-source', '20'],
+        (21, '19+', '19'):     ['-target', '20', '-source', '20'],
+        (22, '19+', '20'):     ['-target', '21', '-source', '21'],
+        (22, '19+', '19..20'): ['-target', '21', '-source', '21'],
+    }
+    for k, expect in get_release_args_data.items():
+        jdk_compliance = JavaCompliance(k[0])
+        project_compliance = JavaCompliance(k[1])
+        javaPreviewNeeded = JavaCompliance(k[2]) if k[2] else None
+        actual = mx.JavacLikeCompiler.get_release_args(jdk_compliance, project_compliance, javaPreviewNeeded)
+        assert actual == expect, f'{k}: {actual} != {expect}'
+
     if mx.is_windows():
         def win(s, min_length=0):
             extra = min_length - len(s)
@@ -1548,7 +1567,7 @@ def _visit_deps(dep, edge):
         exclude_dirs.extend(p.source_dirs())
         exclude_dirs.append(p.source_gen_dir())
 
-    javaCompliance = max([p.javaCompliance for p in includes]) if includes else mx.JavaCompliance('1.7')
+    javaCompliance = max([p.javaCompliance for p in includes]) if includes else JavaCompliance('1.7')
 
     jacoco_exec = get_jacoco_dest_file()
     if not os.path.exists(jacoco_exec) and not args.skip_coverage: