Clarify toolchain support

1. Document what the main plugins are for.
2. The "compile" version is actually the "compiler" version (the version of the compiler),
   and shouldn't be mistaken for the "version we compile to". Renaming
   it.

Author: yrodiere

local-build-plugins/src/main/java/org/hibernate/orm/toolchains/JavaModulePlugin.java

@@ -27,6 +27,13 @@
 import org.gradle.jvm.toolchain.JavaToolchainService;
 
 /**
+ * Retrieves JDK versions exposed by {@link JdkVersionPlugin}
+ * and injects them in build tasks.
+ *
+ * @see JdkVersionConfig
+ * @see JdkVersionSettingsPlugin
+ * @see JdkVersionPlugin
+ *
  * @author Steve Ebersole
  */
 public class JavaModulePlugin implements Plugin<Project> {
@@ -57,11 +64,11 @@ public void apply(Project project) {
 			mainCompileTask.setSourceCompatibility( jdkVersionsConfig.getMainReleaseVersion().toString() );
 			mainCompileTask.setTargetCompatibility( jdkVersionsConfig.getMainReleaseVersion().toString() );
 
-			testCompileTask.setSourceCompatibility( jdkVersionsConfig.getTestCompileVersion().toString() );
-			testCompileTask.setTargetCompatibility( jdkVersionsConfig.getTestCompileVersion().toString() );
+			testCompileTask.setSourceCompatibility( jdkVersionsConfig.getTestCompilerVersion().toString() );
+			testCompileTask.setTargetCompatibility( jdkVersionsConfig.getTestCompilerVersion().toString() );
 		}
 		else {
-			javaPluginExtension.getToolchain().getLanguageVersion().set( jdkVersionsConfig.getMainCompileVersion() );
+			javaPluginExtension.getToolchain().getLanguageVersion().set( jdkVersionsConfig.getMainCompilerVersion() );
 
 			configureCompileTasks( project );
 			configureTestTasks( project );
@@ -72,7 +79,7 @@ public void apply(Project project) {
 
 			testCompileTask.getJavaCompiler().set(
 					toolchainService.compilerFor( javaToolchainSpec -> {
-						javaToolchainSpec.getLanguageVersion().set( jdkVersionsConfig.getTestCompileVersion() );
+						javaToolchainSpec.getLanguageVersion().set( jdkVersionsConfig.getTestCompilerVersion() );
 					} )
 			);
 			if ( testTask != null ) {

local-build-plugins/src/main/java/org/hibernate/orm/toolchains/JdkVersionConfig.java

@@ -19,6 +19,10 @@
 /**
  * Describes the JDK versions of interest to the Hibernate build
  *
+ * @see JdkVersionSettingsPlugin
+ * @see JdkVersionPlugin
+ * @see JavaModulePlugin
+ *
  * @author Steve Ebersole
  */
 public class JdkVersionConfig {
@@ -36,15 +40,15 @@ public JdkVersionConfig(
 			boolean explicit,
 			JavaLanguageVersion baseline,
 			JavaLanguageVersion max,
-			JavaLanguageVersion mainCompileVersion,
+			JavaLanguageVersion mainCompilerVersion,
 			JavaLanguageVersion mainReleaseVersion,
 			JavaLanguageVersion testCompileVersion,
 			JavaLanguageVersion testReleaseVersion,
 			JavaLanguageVersion testLauncherVersion) {
 		this.explicit = explicit;
 		this.baseline = baseline;
 		this.max = max;
-		this.main = new MainJdks( mainCompileVersion, mainReleaseVersion );
+		this.main = new MainJdks( mainCompilerVersion, mainReleaseVersion );
 		this.test = new TestJdks( testCompileVersion, testReleaseVersion, testLauncherVersion );
 	}
 
@@ -88,16 +92,16 @@ public TestJdks getTest() {
 		return test;
 	}
 
-	public JavaLanguageVersion getMainCompileVersion() {
-		return main.getCompile();
+	public JavaLanguageVersion getMainCompilerVersion() {
+		return main.getCompiler();
 	}
 
 	public JavaLanguageVersion getMainReleaseVersion() {
 		return main.getRelease();
 	}
 
-	public JavaLanguageVersion getTestCompileVersion() {
-		return test.getCompile();
+	public JavaLanguageVersion getTestCompilerVersion() {
+		return test.getCompiler();
 	}
 
 	public JavaLanguageVersion getTestReleaseVersion() {
@@ -110,9 +114,9 @@ public JavaLanguageVersion getTestLauncherVersion() {
 
 	public Set<JavaLanguageVersion> getAllVersions() {
 		final HashSet<JavaLanguageVersion> versions = new HashSet<>();
-		versions.add( getMainCompileVersion() );
+		versions.add( getMainCompilerVersion() );
 		versions.add( getMainReleaseVersion() );
-		versions.add( getTestCompileVersion() );
+		versions.add( getTestCompilerVersion() );
 		versions.add( getTestReleaseVersion() );
 		versions.add( getTestLauncherVersion() );
 		return versions;
@@ -127,37 +131,37 @@ public static JdkVersionConfig createVersionConfig(
 			JavaLanguageVersion maxSupportedJdkVersion) {
 		final boolean explicitlyConfigured = explicitMainVersion != null || explicitTestVersion != null;
 
-		final JavaLanguageVersion mainCompileVersion;
+		final JavaLanguageVersion mainCompilerVersion;
 		final JavaLanguageVersion mainReleaseVersion;
-		final JavaLanguageVersion testCompileVersion;
+		final JavaLanguageVersion testCompilerVersion;
 		final JavaLanguageVersion testReleaseVersion;
 		final JavaLanguageVersion testLauncherVersion;
 
 		if ( explicitlyConfigured ) {
-			mainCompileVersion = requireNonNullElse( explicitMainVersion, baselineJdkVersion );
-			testCompileVersion = requireNonNullElse( explicitTestVersion, baselineJdkVersion );
+			mainCompilerVersion = requireNonNullElse( explicitMainVersion, baselineJdkVersion );
+			testCompilerVersion = requireNonNullElse( explicitTestVersion, baselineJdkVersion );
 			mainReleaseVersion = baselineJdkVersion;
 
-			if ( testCompileVersion.asInt() > maxSupportedJdkVersion.asInt() ) {
+			if ( testCompilerVersion.asInt() > maxSupportedJdkVersion.asInt() ) {
 				System.out.println(
-						"[WARN] Gradle does not support bytecode version '" + testCompileVersion + "'."
+						"[WARN] Gradle does not support bytecode version '" + testCompilerVersion + "'."
 								+ " Forcing test bytecode to version " + maxSupportedJdkVersion + "."
 				);
 				testReleaseVersion = maxSupportedJdkVersion;
 			}
 			else {
-				testReleaseVersion = testCompileVersion;
+				testReleaseVersion = testCompilerVersion;
 			}
 
-			testLauncherVersion = testCompileVersion;
+			testLauncherVersion = testCompilerVersion;
 
 			return new JdkVersionConfig(
 					true,
 					baselineJdkVersion,
 					maxSupportedJdkVersion,
-					mainCompileVersion,
+					mainCompilerVersion,
 					mainReleaseVersion,
-					testCompileVersion,
+					testCompilerVersion,
 					testReleaseVersion,
 					testLauncherVersion
 			);
@@ -219,25 +223,17 @@ public static JavaLanguageVersion extractVersion(Project project, String propert
 		return null;
 	}
 
-
-
-
 	public static class MainJdks implements JdkVersionCombo {
-		private final JavaLanguageVersion compileVersion;
+		private final JavaLanguageVersion compilerVersion;
 		private final JavaLanguageVersion releaseVersion;
 
-		public MainJdks(JavaLanguageVersion compileVersion, JavaLanguageVersion releaseVersion) {
-			this.compileVersion = compileVersion;
+		public MainJdks(JavaLanguageVersion compilerVersion, JavaLanguageVersion releaseVersion) {
+			this.compilerVersion = compilerVersion;
 			this.releaseVersion = releaseVersion;
 		}
 
-		@Override
-		public JavaLanguageVersion getCompile() {
-			return compileVersion;
-		}
-
 		public JavaLanguageVersion getCompiler() {
-			return compileVersion;
+			return compilerVersion;
 		}
 
 		@Override
@@ -247,31 +243,27 @@ public JavaLanguageVersion getRelease() {
 
 		@Override
 		public String toString() {
-			return "[compile: " + compileVersion + ", release:" + releaseVersion + "]";
+			return "[compiler: " + compilerVersion + ", release:" + releaseVersion + "]";
 		}
 	}
 
 	public static class TestJdks implements JdkVersionCombo {
-		private final JavaLanguageVersion compileVersion;
+		private final JavaLanguageVersion compilerVersion;
 		private final JavaLanguageVersion releaseVersion;
 		private final JavaLanguageVersion launcherVersion;
 
 		public TestJdks(
-				JavaLanguageVersion compileVersion,
+				JavaLanguageVersion compilerVersion,
 				JavaLanguageVersion releaseVersion,
 				JavaLanguageVersion launcherVersion) {
-			this.compileVersion = compileVersion;
+			this.compilerVersion = compilerVersion;
 			this.releaseVersion = releaseVersion;
 			this.launcherVersion = launcherVersion;
 		}
 
-		public JavaLanguageVersion getCompiler() {
-			return compileVersion;
-		}
-
 		@Override
-		public JavaLanguageVersion getCompile() {
-			return compileVersion;
+		public JavaLanguageVersion getCompiler() {
+			return compilerVersion;
 		}
 
 		@Override
@@ -285,12 +277,12 @@ public JavaLanguageVersion getLauncher() {
 
 		@Override
 		public String toString() {
-			return "[compile: " + compileVersion + ", release:" + releaseVersion + ", launcher: " + launcherVersion + "]";
+			return "[compiler: " + compilerVersion + ", release:" + releaseVersion + ", launcher: " + launcherVersion + "]";
 		}
 	}
 
 	public interface  JdkVersionCombo {
-		JavaLanguageVersion getCompile();
+		JavaLanguageVersion getCompiler();
 		JavaLanguageVersion getRelease();
 	}
 }

local-build-plugins/src/main/java/org/hibernate/orm/toolchains/JdkVersionPlugin.java

@@ -23,6 +23,13 @@
 import static org.hibernate.orm.toolchains.JdkVersionConfig.extractVersion;
 
 /**
+ * Gathers JDK versions of interest from settings and exposes them to later phases of the build
+ * than {@link JdkVersionSettingsPlugin}.
+ *
+ * @see JdkVersionConfig
+ * @see JdkVersionSettingsPlugin
+ * @see JavaModulePlugin
+ *
  * @author Steve Ebersole
  */
 public class JdkVersionPlugin implements Plugin<Project> {

local-build-plugins/src/main/java/org/hibernate/orm/toolchains/JdkVersionSettingsPlugin.java

@@ -18,6 +18,13 @@
 import static org.hibernate.orm.toolchains.JdkVersionConfig.extractVersion;
 
 /**
+ * Gathers JDK versions of interest from settings and exposes them to earlier phases of the build
+ * than {@link JdkVersionPlugin}.
+ *
+ * @see JdkVersionConfig
+ * @see JdkVersionPlugin
+ * @see JavaModulePlugin
+ *
  * @author Steve Ebersole
  */
 public class JdkVersionSettingsPlugin implements Plugin<Settings> {