Prefer Class-File API on Java 24 or above

CONTRIBUTING.md

@@ -5,7 +5,7 @@ help you get started.
 
 ## Prerequisites
 
-- **Java Development Kit (JDK)**: JDK 17 or higher is required to build the project. JDK 25 is recommended.
+- **Java Development Kit (JDK)**: JDK 25 or higher is required to build the project.
 - **Gradle**: The project uses the Gradle Wrapper, so you do not need to install Gradle globally. Run command-line tasks
   using `./gradlew` (or `gradlew.bat` on Windows).
 

build.gradle.kts

@@ -4,10 +4,13 @@ import org.gradle.api.plugins.JavaPlugin.API_ELEMENTS_CONFIGURATION_NAME
 import org.gradle.api.plugins.JavaPlugin.JAVADOC_ELEMENTS_CONFIGURATION_NAME
 import org.gradle.api.plugins.JavaPlugin.RUNTIME_ELEMENTS_CONFIGURATION_NAME
 import org.gradle.api.plugins.JavaPlugin.SOURCES_ELEMENTS_CONFIGURATION_NAME
+import org.gradle.language.base.plugins.LifecycleBasePlugin.VERIFICATION_GROUP
 import org.gradle.plugin.compatibility.compatibility
 import org.jetbrains.kotlin.gradle.dsl.JvmDefaultMode
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.dsl.KotlinJvmCompilerOptions
 import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
+import org.jetbrains.kotlin.gradle.dsl.abi.BinariesSource
 import org.jetbrains.kotlin.gradle.dsl.abi.ExperimentalAbiValidation
 
 plugins {
@@ -30,7 +33,11 @@ dokka { dokkaPublications.html { outputDirectory = rootDir.resolve("docs/api") }
 
 kotlin {
   explicitApi()
-  @OptIn(ExperimentalAbiValidation::class) abiValidation()
+  @OptIn(ExperimentalAbiValidation::class)
+  abiValidation {
+    // Check APIs under main and versioned source sets.
+    binariesSource = BinariesSource.NON_TEST_COMPILATIONS
+  }
   val jdkRelease = "17"
   compilerOptions {
     allWarningsAsErrors = true
@@ -46,6 +53,8 @@ kotlin {
   }
 }
 
+addMultiReleaseSourceSet(24)
+
 lint {
   baseline = file("gradle/lint-baseline.xml")
   ignoreTestFixturesSources = true
@@ -246,6 +255,10 @@ buildConfig {
   }
 }
 
+tasks.jar {
+  manifest.attributes("Multi-Release" to true)
+}
+
 tasks.pluginUnderTestMetadata { pluginClasspath.from(testPluginClasspath) }
 
 tasks.check { dependsOn(tasks.withType<Test>()) }
@@ -260,3 +273,63 @@ tasks.clean {
       rootDir.resolve("site"),
     )
 }
+
+fun addMultiReleaseSourceSet(version: Int) {
+  kotlin.target.compilations.create("java${version}") {
+    associateWith(kotlin.target.compilations.getByName("main"))
+    compileTaskProvider {
+      compilerOptions {
+        this@compilerOptions as KotlinJvmCompilerOptions
+        jvmTarget = JvmTarget.fromTarget(version.toString())
+        freeCompilerArgs.add("-Xjdk-release=$version")
+      }
+    }
+    compileJavaTaskProvider { options.release = version }
+
+    tasks.jar { from(output.allOutputs) { into("META-INF/versions/$version") } }
+
+    val versionedTest =
+      tasks.register("testJava${version}", Test::class) {
+        useJUnitPlatform()
+        group = VERIFICATION_GROUP
+        description = "Runs test suite using Java $version toolchain."
+        val testSourceSet = sourceSets.test.get()
+        testClassesDirs = testSourceSet.output.classesDirs
+        val testCpWithoutMainOutput = testSourceSet.runtimeClasspath - sourceSets.main.get().output
+        // Prefer MR classes on the classpath, so remove main output.
+        classpath = files(tasks.jar.flatMap { it.archiveFile }) + testCpWithoutMainOutput
+        javaLauncher = javaToolchains.launcherFor {
+          languageVersion = JavaLanguageVersion.of(version)
+        }
+      }
+
+    val validateMultiReleaseJar =
+      with(tasks) {
+        if ("validateMultiReleaseJar" in names) {
+          named("validateMultiReleaseJar")
+        } else {
+          register("validateMultiReleaseJar", JavaExec::class) {
+            group = VERIFICATION_GROUP
+            description = "Validates the multi-release JAR."
+            mainModule = "jdk.jartool"
+            mainClass = "sun.tools.jar.Main"
+            val jarFile = jar.flatMap { it.archiveFile }
+            inputs.file(jarFile)
+            argumentProviders.add(
+              CommandLineArgumentProvider {
+                // https://docs.oracle.com/en/java/javase/25/docs/specs/man/jar.html
+                listOf("--validate", "--file", jarFile.get().asFile.absolutePath)
+              }
+            )
+          }
+        }
+      }
+
+    tasks.check {
+      dependsOn(
+        versionedTest,
+        validateMultiReleaseJar,
+      )
+    }
+  }
+}

gradle.properties

@@ -2,6 +2,11 @@
 # https://kotlinlang.org/docs/gradle-configure-project.html#dependency-on-the-standard-library
 kotlin.stdlib.default.dependency=false
 
+# Keep associated Kotlin compilations from depending on archive tasks (e.g., jar), which can create circular task graphs in multi-release setups.
+# https://kotlinlang.org/docs/gradle-configure-project.html#disable-use-of-artifact-in-compilation-task
+# https://kotlinlang.org/docs/whatsnew2020.html#added-task-dependency-for-rare-cases-when-the-compile-task-lacks-one-on-an-artifact
+kotlin.build.archivesTaskOutputAsFriendModule=false
+
 org.gradle.caching=true
 org.gradle.configuration-cache=true
 org.gradle.configuration-cache.parallel=true

settings.gradle.kts

@@ -12,7 +12,10 @@ pluginManagement {
   }
 }
 
-plugins { id("com.gradle.develocity") version "4.5.0" }
+plugins {
+  id("com.gradle.develocity") version "4.5.0"
+  id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0"
+}
 
 develocity {
   buildScan {
@@ -42,3 +45,7 @@ rootProject.name = "shadow"
 enableFeaturePreview("NO_IMPLICIT_LOOKUP_IN_PARENT_PROJECTS")
 
 enableFeaturePreview("STABLE_CONFIGURATION_CACHE")
+
+check(JavaVersion.current() >= JavaVersion.VERSION_25) {
+  "Needs Java 25 or above to run, the current is ${JavaVersion.current()}"
+}