Upgrade GraalVM and Truffle, set up multi-JDK testing, bump development Java to 21 (#876)

This updates the GraalVM and Truffle libraries to 2024.1.2.

This also updates the build logic to compile Java sources using Java 21, due to some compile-only dependencies within GraalVM/Truffle using class file version 65. However, the produced artifact is still compatible with Java 17.

This also changes the Gradle build logic to use toolchains, and to test the Java libraries with JDK 17 and 21.

One consequence of this change is that Truffle is no longer shaded within the fat jars.

feat: support for jvm21+ toolchain
feat: support for gradle toolchains
feat: pass -PnativeArch=native to build with -march=native
test: multi-jdk testing support
test: support for jvm-test-suite plugin
test: add tasks to run jpkl eval on multiple jdks
test: make jdk exec tests respect multi-jdk flags and ranges
fix: remove mrjar classes at >jvm17 from fatjars
fix: use jdk21 to run the tests (needed for Unsafe.ensureInitialized)
fix: truffle svm dependency is required after graalvm 24.0.0
fix: warnings for gvm flag usage, renamed truffle svm macro
fix: build with --add-modules=jdk.unsupported where needed
fix: don't use gu tool for modern graalvm versions
fix: catch Throwable instead of deprecated-for-removal ThreadDeath
chore: buildinfo changes for JVM targets, toolchains
chore: enforce testing at exactly jdk21
chore: enforce build tooling at jdk21+
chore: bump graalvm/truffle libs → 24.1.2
chore: toolchains for buildSrc

Signed-off-by: Sam Gammon <sam@elide.dev>

buildSrc/build.gradle.kts

@@ -15,7 +15,13 @@
  */
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
-plugins { `kotlin-dsl` }
+plugins {
+  `kotlin-dsl`
+  `jvm-toolchains`
+}
+
+// Keep this in sync with the constants in `BuildInfo.kt` (those are not addressable here).
+val toolchainVersion = 21
 
 dependencies {
   implementation(libs.downloadTaskPlugin)
@@ -29,8 +35,16 @@ dependencies {
 }
 
 java {
-  sourceCompatibility = JavaVersion.VERSION_17
-  targetCompatibility = JavaVersion.VERSION_17
+  sourceCompatibility = JavaVersion.toVersion(toolchainVersion)
+  targetCompatibility = JavaVersion.toVersion(toolchainVersion)
+
+  toolchain {
+    languageVersion = JavaLanguageVersion.of(toolchainVersion)
+    vendor = JvmVendorSpec.ADOPTIUM
+  }
 }
 
-kotlin { compilerOptions { jvmTarget = JvmTarget.JVM_17 } }
+kotlin {
+  jvmToolchain(toolchainVersion)
+  compilerOptions { jvmTarget = JvmTarget.fromTarget(toolchainVersion.toString()) }
+}

buildSrc/settings.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -24,6 +24,8 @@ pluginManagement {
   }
 }
 
+plugins { id("org.gradle.toolchains.foojay-resolver-convention") }
+
 // makes ~/.gradle/init.gradle unnecessary and ~/.gradle/gradle.properties optional
 dependencyResolutionManagement {
   // use same version catalog as main build

buildSrc/src/main/kotlin/BuildInfo.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,11 +19,56 @@ import java.io.File
 import org.gradle.api.Project
 import org.gradle.api.artifacts.VersionCatalog
 import org.gradle.api.artifacts.VersionCatalogsExtension
-import org.gradle.kotlin.dsl.getByType
+import org.gradle.api.attributes.Category
+import org.gradle.api.plugins.JvmTestSuitePlugin
+import org.gradle.api.plugins.jvm.JvmTestSuite
+import org.gradle.api.provider.Provider
+import org.gradle.api.tasks.TaskProvider
+import org.gradle.api.tasks.testing.Test
+import org.gradle.internal.extensions.stdlib.capitalized
+import org.gradle.jvm.toolchain.*
+import org.gradle.kotlin.dsl.*
+import org.gradle.kotlin.dsl.support.serviceOf
+import org.gradle.process.CommandLineArgumentProvider
+import org.gradle.testing.base.TestingExtension
+
+/**
+ * JVM bytecode target; this is pinned at a reasonable version, because downstream JVM projects
+ * which consume Pkl will need a minimum Bytecode level at or above this one.
+ *
+ * Kotlin and Java need matching bytecode targets, so this is expressed as a build setting and
+ * constant default. To override, pass `-DpklJdkToolchain=X` to the Gradle command line, where X is
+ * a major Java version.
+ */
+const val PKL_JVM_TARGET_DEFAULT_MAXIMUM = 17
+
+/**
+ * The Pkl build requires JDK 21+ to build, because JDK 17 is no longer within the default set of
+ * supported JDKs for GraalVM. This is a build-time requirement, not a runtime requirement.
+ */
+const val PKL_JDK_VERSION_MIN = 21
+
+/**
+ * The JDK minimum is set to match the bytecode minimum, to guarantee that fat JARs work against the
+ * earliest supported bytecode target.
+ */
+const val PKL_TEST_JDK_MINIMUM = PKL_JVM_TARGET_DEFAULT_MAXIMUM
+
+/**
+ * Maximum JDK version which Pkl is tested with; this should be bumped when new JDK stable releases
+ * are issued. At the time of this writing, JDK 23 is the latest available release.
+ */
+const val PKL_TEST_JDK_MAXIMUM = 23
+
+/**
+ * Test the full suite of JDKs between [PKL_TEST_JDK_MINIMUM] and [PKL_TEST_JDK_MAXIMUM]; if this is
+ * set to `false` (or overridden on the command line), only LTS releases are tested by default.
+ */
+const val PKL_TEST_ALL_JDKS = false
 
 // `buildInfo` in main build scripts
 // `project.extensions.getByType<BuildInfo>()` in precompiled script plugins
-open class BuildInfo(project: Project) {
+open class BuildInfo(private val project: Project) {
   inner class GraalVm(val arch: String) {
     val homeDir: String by lazy {
       System.getenv("GRAALVM_HOME") ?: "${System.getProperty("user.home")}/.graalvm"
@@ -80,6 +125,220 @@ open class BuildInfo(project: Project) {
 
   val isReleaseBuild: Boolean by lazy { java.lang.Boolean.getBoolean("releaseBuild") }
 
+  val isNativeArch: Boolean by lazy { java.lang.Boolean.getBoolean("nativeArch") }
+
+  val jvmTarget: Int by lazy {
+    System.getProperty("pklJvmTarget")?.toInt() ?: PKL_JVM_TARGET_DEFAULT_MAXIMUM
+  }
+
+  // JPMS exports for Truffle; needed on some versions of Java, and transitively within some JARs.
+  private val jpmsExports =
+    arrayOf(
+      "org.graalvm.truffle/com.oracle.truffle.api.exception=ALL-UNNAMED",
+      "org.graalvm.truffle/com.oracle.truffle.api=ALL-UNNAMED",
+      "org.graalvm.truffle/com.oracle.truffle.api.nodes=ALL-UNNAMED",
+      "org.graalvm.truffle/com.oracle.truffle.api.source=ALL-UNNAMED",
+    )
+
+  // Extra JPMS modules forced onto the module path via `--add-modules` in some cases.
+  private val jpmsAddModules = arrayOf("jdk.unsupported")
+
+  // Formats `jpmsExports` for use in JAR manifest attributes.
+  val jpmsExportsForJarManifest: String by lazy {
+    jpmsExports.joinToString(" ") { it.substringBefore("=") }
+  }
+
+  // Formats `jpmsExports` for use on the command line with `--add-exports`.
+  val jpmsExportsForAddExportsFlags: Collection<String> by lazy {
+    jpmsExports.map { "--add-exports=$it" }
+  }
+
+  // Formats `jpmsAddModules` for use on the command line with `--add-modules`.
+  val jpmsAddModulesFlags: Collection<String> by lazy { jpmsAddModules.map { "--add-modules=$it" } }
+
+  // JVM properties to set during testing.
+  val testProperties =
+    mapOf<String, Any>(
+      // @TODO: this should be removed once pkl supports JPMS as a true Java Module.
+      "polyglotimpl.DisableClassPathIsolation" to true
+    )
+
+  val jdkVendor: JvmVendorSpec = JvmVendorSpec.ADOPTIUM
+
+  val jdkToolchainVersion: JavaLanguageVersion by lazy {
+    JavaLanguageVersion.of(System.getProperty("pklJdkToolchain")?.toInt() ?: PKL_JDK_VERSION_MIN)
+  }
+
+  val jdkTestFloor: JavaLanguageVersion by lazy { JavaLanguageVersion.of(PKL_TEST_JDK_MINIMUM) }
+
+  val jdkTestCeiling: JavaLanguageVersion by lazy { JavaLanguageVersion.of(PKL_TEST_JDK_MAXIMUM) }
+
+  val testAllJdks: Boolean by lazy {
+    // By default, Pkl is tested against LTS JDK releases within the bounds of `PKL_TEST_JDK_TARGET`
+    // and `PKL_TEST_JDK_MAXIMUM`. To test against the full suite of JDK versions, past and present,
+    // set `-DpklTestAllJdks=true` on the Gradle command line. This results in non-LTS releases, old
+    // releases, and "experimental releases" (newer than the toolchain version) being included in
+    // the default `check` suite.
+    System.getProperty("pklTestAllJdks")?.toBoolean() ?: PKL_TEST_ALL_JDKS
+  }
+
+  val testExperimentalJdks: Boolean by lazy {
+    System.getProperty("pklTestFutureJdks")?.toBoolean() ?: false
+  }
+
+  val testJdkVendors: Sequence<JvmVendorSpec> by lazy {
+    // By default, only OpenJDK is tested during multi-JDK testing. Flip `-DpklTestAllVendors=true`
+    // to additionally test against a suite of JDK vendors, including Azul, Oracle, and GraalVM.
+    when (System.getProperty("pklTestAllVendors")?.toBoolean()) {
+      true -> sequenceOf(JvmVendorSpec.ADOPTIUM, JvmVendorSpec.GRAAL_VM, JvmVendorSpec.ORACLE)
+      else -> sequenceOf(JvmVendorSpec.ADOPTIUM)
+    }
+  }
+
+  // Assembles a collection of JDK versions which tests can be run against, considering ancillary
+  // parameters like `testAllJdks` and `testExperimentalJdks`.
+  val jdkTestRange: Collection<JavaLanguageVersion> by lazy {
+    JavaVersionRange.inclusive(jdkTestFloor, jdkTestCeiling).filter { version ->
+      // unless we are instructed to test all JDKs, tests only include LTS releases and
+      // versions above the toolchain version.
+      testAllJdks || (JavaVersionRange.isLTS(version) || version >= jdkToolchainVersion)
+    }
+  }
+
+  private fun JavaToolchainSpec.pklJdkToolchain() {
+    languageVersion.set(jdkToolchainVersion)
+    vendor.set(jdkVendor)
+  }
+
+  private fun labelForVendor(vendor: JvmVendorSpec): String =
+    when (vendor) {
+      JvmVendorSpec.AZUL -> "Zulu"
+      JvmVendorSpec.GRAAL_VM -> "GraalVm"
+      JvmVendorSpec.ORACLE -> "Oracle"
+      JvmVendorSpec.ADOPTIUM -> "Adoptium"
+      else -> error("Unrecognized JDK vendor: $vendor")
+    }
+
+  private fun testNamer(baseName: () -> String): (JavaLanguageVersion, JvmVendorSpec?) -> String =
+    { jdkTarget, vendor ->
+      val targetToken =
+        when (vendor) {
+          null -> "Jdk${jdkTarget.asInt()}"
+          else -> "Jdk${jdkTarget.asInt()}${labelForVendor(vendor).capitalized()}"
+        }
+      if (jdkTarget > jdkToolchainVersion) {
+        // test targets above the toolchain target are considered "experimental".
+        "${baseName()}${targetToken}Experimental"
+      } else {
+        "${baseName()}${targetToken}"
+      }
+    }
+
+  @Suppress("UnstableApiUsage")
+  fun multiJdkTestingWith(
+    templateTask: TaskProvider<out Test>,
+    configurator: MultiJdkTestConfigurator = {},
+  ): Iterable<Provider<out Any>> =
+    with(project) {
+      // force the `jvm-test-suite` plugin to apply first
+      project.pluginManager.apply(JvmTestSuitePlugin::class.java)
+
+      val isMultiVendor = testJdkVendors.count() > 1
+      val baseNameProvider = { templateTask.get().name }
+      val namer = testNamer(baseNameProvider)
+      val applyConfig: MultiJdkTestConfigurator = { (version, jdk) ->
+        // 1) copy configurations from the template task
+        dependsOn(templateTask)
+        templateTask.get().let { template ->
+          classpath = template.classpath
+          testClassesDirs = template.testClassesDirs
+          jvmArgs.addAll(template.jvmArgs)
+          jvmArgumentProviders.addAll(template.jvmArgumentProviders)
+          forkEvery = template.forkEvery
+          maxParallelForks = template.maxParallelForks
+          minHeapSize = template.minHeapSize
+          maxHeapSize = template.maxHeapSize
+          exclude(template.excludes)
+          template.systemProperties.forEach { prop -> systemProperty(prop.key, prop.value) }
+        }
+
+        // 2) assign launcher
+        javaLauncher = jdk
+
+        // 3) dispatch the user's configurator
+        configurator(version to jdk)
+      }
+
+      serviceOf<JavaToolchainService>().let { toolchains ->
+        jdkTestRange
+          .flatMap { targetVersion ->
+            // multiply out by jdk vendor
+            testJdkVendors.map { vendor -> (targetVersion to vendor) }
+          }
+          .filter { (jdkTarget, vendor) ->
+            // only include experimental tasks in the return suite if the flag is set. if the task
+            // is withheld from the returned list, it will not be executed by default with `gradle
+            // check`.
+            testExperimentalJdks ||
+              (!namer(jdkTarget, vendor.takeIf { isMultiVendor }).contains("Experimental"))
+          }
+          .map { (jdkTarget, vendor) ->
+            if (jdkToolchainVersion == jdkTarget)
+              tasks.register(namer(jdkTarget, vendor)) {
+                // alias to `test`
+                dependsOn(templateTask)
+                group = Category.VERIFICATION
+                description =
+                  "Alias for regular '${baseNameProvider()}' task, on JDK ${jdkTarget.asInt()}"
+              }
+            else
+              the<TestingExtension>().suites.register(
+                namer(jdkTarget, vendor.takeIf { isMultiVendor }),
+                JvmTestSuite::class,
+              ) {
+                targets.all {
+                  testTask.configure {
+                    group = Category.VERIFICATION
+                    description = "Run tests against JDK ${jdkTarget.asInt()}"
+                    applyConfig(jdkTarget to toolchains.launcherFor { languageVersion = jdkTarget })
+
+                    // fix: on jdk17, we must force the polyglot module on to the modulepath
+                    if (jdkTarget.asInt() == 17)
+                      jvmArgumentProviders.add(
+                        CommandLineArgumentProvider {
+                          buildList { listOf("--add-modules=org.graalvm.polyglot") }
+                        }
+                      )
+                  }
+                }
+              }
+          }
+          .toList()
+      }
+    }
+
+  val javaCompiler: Provider<JavaCompiler> by lazy {
+    project.serviceOf<JavaToolchainService>().let { toolchainService ->
+      toolchainService.compilerFor { pklJdkToolchain() }
+    }
+  }
+
+  val javaTestLauncher: Provider<JavaLauncher> by lazy {
+    project.serviceOf<JavaToolchainService>().let { toolchainService ->
+      toolchainService.launcherFor { pklJdkToolchain() }
+    }
+  }
+
+  val multiJdkTesting: Boolean by lazy {
+    // By default, Pkl is tested against a full range of JDK versions, past and present, within the
+    // supported bounds of `PKL_TEST_JDK_TARGET` and `PKL_TEST_JDK_MAXIMUM`. To opt-out of this
+    // behavior, set `-DpklMultiJdkTesting=false` on the Gradle command line.
+    //
+    // In CI, this defaults to `true` to catch potential cross-JDK compat regressions or other bugs.
+    // In local dev, this defaults to `false` to speed up the build and reduce contributor load.
+    System.getProperty("pklMultiJdkTesting")?.toBoolean() ?: isCiBuild
+  }
+
   val hasMuslToolchain: Boolean by lazy {
     // see "install musl" in .circleci/jobs/BuildNativeJob.pkl
     File(System.getProperty("user.home"), "staticdeps/bin/x86_64-linux-musl-gcc").exists()
@@ -136,3 +395,7 @@ open class BuildInfo(project: Project) {
     }
   }
 }
+
+// Shape of a function which is applied to configure multi-JDK testing.
+private typealias MultiJdkTestConfigurator =
+  Test.(Pair<JavaLanguageVersion, Provider<JavaLauncher>>) -> Unit

buildSrc/src/main/kotlin/InstallGraalVm.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -30,7 +30,7 @@ abstract class InstallGraalVm
 @Inject
 constructor(
   private val fileOperations: FileOperations,
-  private val execOperations: ExecOperations
+  private val execOperations: ExecOperations,
 ) : DefaultTask() {
   @get:Input abstract val graalVm: Property<BuildInfo.GraalVm>
 
@@ -58,10 +58,16 @@ constructor(
         if (os.isMacOsX) distroDir.resolve("Contents/Home/bin") else distroDir.resolve("bin")
 
       println("Installing native-image into $distroDir")
-      execOperations.exec {
-        val executableName = if (os.isWindows) "gu.cmd" else "gu"
-        executable = distroBinDir.resolve(executableName).toString()
-        args("install", "--no-progress", "native-image")
+      val gvmVersionMajor =
+        requireNotNull(graalVm.get().version.split(".").first().toIntOrNull()) {
+          "Invalid GraalVM JDK version: ${graalVm.get().graalVmJdkVersion}"
+        }
+      if (gvmVersionMajor < 24) {
+        execOperations.exec {
+          val executableName = if (os.isWindows) "gu.cmd" else "gu"
+          executable = distroBinDir.resolve(executableName).toString()
+          args("install", "--no-progress", "native-image")
+        }
       }
 
       println("Creating symlink ${graalVm.get().installDir} for $distroDir")

buildSrc/src/main/kotlin/JavaVersionRange.kt

@@ -0,0 +1,64 @@
+/*
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+@file:Suppress("MemberVisibilityCanBePrivate")
+
+import java.util.*
+import org.gradle.jvm.toolchain.JavaLanguageVersion
+
+typealias JavaVersionPair = Pair<JavaLanguageVersion, JavaLanguageVersion>
+
+// All LTS releases.
+private val ltsReleases =
+  sortedSetOf(
+    JavaLanguageVersion.of(8),
+    JavaLanguageVersion.of(11),
+    JavaLanguageVersion.of(17),
+    JavaLanguageVersion.of(21),
+  )
+
+/** Describes an inclusive range of JVM versions, based on the [JavaLanguageVersion] type. */
+@JvmInline
+value class JavaVersionRange private constructor(private val bounds: JavaVersionPair) :
+  Iterable<JavaLanguageVersion> {
+  @Suppress("unused")
+  companion object {
+    fun isLTS(version: JavaLanguageVersion): Boolean = version in ltsReleases
+
+    fun inclusive(floor: JavaLanguageVersion, ceiling: JavaLanguageVersion): JavaVersionRange =
+      JavaVersionRange(floor to ceiling)
+
+    fun startingAt(floor: JavaLanguageVersion): JavaVersionRange =
+      inclusive(floor, JavaLanguageVersion.of(PKL_TEST_JDK_MAXIMUM))
+
+    fun upTo(ceiling: JavaLanguageVersion): JavaVersionRange =
+      inclusive(JavaLanguageVersion.of(PKL_TEST_JDK_MINIMUM), ceiling)
+  }
+
+  operator fun contains(version: JavaLanguageVersion): Boolean =
+    version >= bounds.first && version <= bounds.second
+
+  fun asSequence(): Sequence<JavaLanguageVersion> = sequence {
+    var current = bounds.first
+    while (current <= bounds.second) {
+      yield(current)
+      current = JavaLanguageVersion.of(current.asInt() + 1)
+    }
+  }
+
+  fun asSortedSet(): SortedSet<JavaLanguageVersion> = asSequence().toSortedSet()
+
+  override fun iterator(): Iterator<JavaLanguageVersion> = asSortedSet().iterator()
+}

buildSrc/src/main/kotlin/pklFatJar.gradle.kts

@@ -40,8 +40,6 @@ val relocations =
   mapOf(
     // pkl-core dependencies
     "org.antlr.v4." to "org.pkl.thirdparty.antlr.v4.",
-    "com.oracle.truffle" to "org.pkl.thirdparty.truffle",
-    "org.graalvm." to "org.pkl.thirdparty.graalvm.",
     "org.organicdesign.fp." to "org.pkl.thirdparty.paguro.",
     "org.snakeyaml.engine." to "org.pkl.thirdparty.snakeyaml.engine.",
     "org.msgpack." to "org.pkl.thirdparty.msgpack.",
@@ -71,7 +69,7 @@ val relocations =
     "com.squareup.kotlinpoet." to "org.pkl.thirdparty.kotlinpoet.",
   )
 
-val nonRelocations = listOf("com/oracle/truffle/")
+val nonRelocations = listOf("com/oracle/truffle/", "org/graalvm/")
 
 tasks.shadowJar {
   inputs.property("relocations", relocations)
@@ -85,7 +83,23 @@ tasks.shadowJar {
 
   exclude("META-INF/maven/**")
   exclude("META-INF/upgrade/**")
-  exclude("META-INF/versions/19/**")
+
+  val info = project.extensions.getByType<BuildInfo>()
+  val minimumJvmTarget = JavaVersion.toVersion(info.jvmTarget)
+
+  manifest.attributes(
+    // Certain exports need to be added to the Java modulepath for Java 17 to work properly with
+    // shaded JARs. See the following link for an explanation of this syntax:
+    // https://bugs.openjdk.org/browse/JDK-8335225
+    "Add-Exports" to info.jpmsExportsForJarManifest
+  )
+
+  // effectively, this results in calls excluding:
+  // `META-INF/versions/{18-25}/**`
+  // at the time of this writing; multi-release JARs beyond JDK 21 break the current
+  // version of the Shadow plugin, and aren't needed for Truffle's use by Pkl.
+  JavaVersionRange.startingAt(JavaLanguageVersion.of(minimumJvmTarget.majorVersion.toInt() + 1))
+    .forEach { exclude("META-INF/versions/${it.asInt()}/**") }
 
   // org.antlr.v4.runtime.misc.RuleDependencyProcessor
   exclude("META-INF/services/javax.annotation.processing.Processor")

buildSrc/src/main/kotlin/pklGradlePluginTest.gradle.kts

@@ -87,7 +87,7 @@ tasks.addRule("Pattern: compatibilityTest[All|Releases|Latest|Candidate|Nightly|
   }
 }
 
-fun createCompatibilityTestTask(versionInfo: GradleVersionInfo) =
+fun createCompatibilityTestTask(versionInfo: GradleVersionInfo): TaskProvider<Test> =
   createCompatibilityTestTask(versionInfo.version, versionInfo.downloadUrl)
 
 fun createCompatibilityTestTask(version: String, downloadUrl: String): TaskProvider<Test> {

buildSrc/src/main/kotlin/pklJavaLibrary.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -13,25 +13,39 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@file:Suppress("HttpUrlsUsage")
+@file:Suppress("HttpUrlsUsage", "unused")
 
 import org.gradle.accessors.dm.LibrariesForLibs
 
 plugins {
   `java-library`
+  `jvm-toolchains`
   id("pklKotlinTest")
   id("com.diffplug.spotless")
 }
 
 // make sources Jar available to other subprojects
-val sourcesJarConfiguration = configurations.register("sourcesJar")
+val sourcesJarConfiguration: Provider<Configuration> = configurations.register("sourcesJar")
 
 // Version Catalog library symbols.
 val libs = the<LibrariesForLibs>()
 
+// Build configuration.
+val info = project.extensions.getByType<BuildInfo>()
+
 java {
+  val jvmTarget = JavaVersion.toVersion(info.jvmTarget)
+
   withSourcesJar() // creates `sourcesJar` task
   withJavadocJar()
+
+  sourceCompatibility = jvmTarget
+  targetCompatibility = jvmTarget
+
+  toolchain {
+    languageVersion = info.jdkToolchainVersion
+    vendor = info.jdkVendor
+  }
 }
 
 artifacts {
@@ -56,7 +70,11 @@ tasks.compileKotlin { enabled = false }
 
 tasks.jar {
   manifest {
-    attributes += mapOf("Automatic-Module-Name" to "org.${project.name.replace("-", ".")}")
+    attributes +=
+      mapOf(
+        "Automatic-Module-Name" to "org.${project.name.replace("-", ".")}",
+        "Add-Exports" to info.jpmsExportsForJarManifest,
+      )
   }
 }
 
@@ -80,9 +98,48 @@ val workAroundKotlinGradlePluginBug by
     }
   }
 
+val truffleJavacArgs =
+  listOf(
+    // TODO: determine correct limits for Truffle specializations
+    // (see https://graalvm.slack.com/archives/CNQSB2DHD/p1712380902746829)
+    "-Atruffle.dsl.SuppressWarnings=truffle-limit"
+  )
+
 tasks.compileJava {
+  javaCompiler = info.javaCompiler
   dependsOn(workAroundKotlinGradlePluginBug)
-  // TODO: determine correct limits for Truffle specializations
-  // (see https://graalvm.slack.com/archives/CNQSB2DHD/p1712380902746829)
-  options.compilerArgs.add("-Atruffle.dsl.SuppressWarnings=truffle-limit")
+  options.compilerArgs.addAll(truffleJavacArgs + info.jpmsAddModulesFlags)
 }
+
+tasks.withType<JavaCompile>().configureEach {
+  val jvmTarget = JavaVersion.toVersion(info.jvmTarget)
+  javaCompiler = info.javaCompiler
+  sourceCompatibility = jvmTarget.majorVersion
+  targetCompatibility = jvmTarget.majorVersion
+}
+
+tasks.withType<JavaExec>().configureEach { jvmArgs(info.jpmsAddModulesFlags) }
+
+fun Test.configureJdkTestTask(launcher: Provider<JavaLauncher>) {
+  useJUnitPlatform()
+  javaLauncher = launcher
+  systemProperties.putAll(info.testProperties)
+  jvmArgs.addAll(info.jpmsAddModulesFlags)
+}
+
+tasks.test { configureJdkTestTask(info.javaTestLauncher) }
+
+// Prepare test tasks for each JDK version which is within the test target suite for Pkl. Each task
+// uses a pinned JDK toolchain version, and is named for the major version which is tested.
+//
+// Test tasks configured in this manner are executed manually by name, e.g. `./gradlew testJdk11`,
+// and automatically as dependencies of `check`.
+//
+// We omit the current JDK from this list because it is already tested, in effect, by the default
+// `test` task.
+//
+// Pkl subprojects may elect to further configure these tasks as needed; by default, each task
+// inherits the configuration of the default `test` task (aside from an overridden launcher).
+val jdkTestTasks = info.multiJdkTestingWith(tasks.test) { (_, jdk) -> configureJdkTestTask(jdk) }
+
+if (info.multiJdkTesting) tasks.check { dependsOn(jdkTestTasks) }

buildSrc/src/main/kotlin/pklKotlinLibrary.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -14,13 +14,15 @@
  * limitations under the License.
  */
 import org.gradle.accessors.dm.LibrariesForLibs
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+import org.jetbrains.kotlin.gradle.tasks.KotlinJvmCompile
 
 plugins {
   id("pklJavaLibrary")
-
   kotlin("jvm")
 }
 
+// Build configuration.
 val buildInfo = project.extensions.getByType<BuildInfo>()
 
 // Version Catalog library symbols.
@@ -38,3 +40,7 @@ dependencies {
 tasks.compileKotlin {
   enabled = true // disabled by pklJavaLibrary
 }
+
+tasks.withType<KotlinJvmCompile>().configureEach {
+  compilerOptions { jvmTarget = JvmTarget.fromTarget(buildInfo.jvmTarget.toString()) }
+}

buildSrc/src/main/kotlin/pklKotlinTest.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,7 +16,10 @@
 import java.net.URI
 import org.gradle.api.tasks.testing.logging.TestExceptionFormat
 
-plugins { kotlin("jvm") }
+plugins {
+  `jvm-test-suite`
+  kotlin("jvm")
+}
 
 val buildInfo = project.extensions.getByType<BuildInfo>()