feat: graalvm jdk21 toolchain

- 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>

Author: sgammon

.java-version

@@ -1 +1 @@
-17.0
+21

DEVELOPMENT.adoc

@@ -7,7 +7,7 @@
 
 == Setup
 
-. (mandatory) Install a JDK (any version between 17 - 21).
+. (mandatory) Install a JDK (JDK 21+ required).
 . (recommended) Install {uri-intellij}[IntelliJ IDEA] +
 To import the project into IntelliJ, go to File->Open and select the project's root directory.
 If the project is opened but not imported, look for a popup in the lower right corner
@@ -17,7 +17,7 @@ _gng_ enables to run Gradle commands with `gw` (instead of `./gradlew`) from any
 . (recommended) Set up Git ignore-revs +
 `git config blame.ignoreRevsFile .git-blame-ignore-revs`
 . (recommended) Install {uri-jenv}[jenv] and plugins +
-_jenv_ use specific JDK versions in certain subdirectories. _Pkl_ comes with a `.java-version` file specifying JDK 17. +
+_jenv_ use specific JDK versions in certain subdirectories. _Pkl_ comes with a `.java-version` file specifying JDK 21. +
 Enable _jenv_ plugins for better handling by `gradle`:
 +
 [source,shell]

bench/gradle.lockfile

@@ -7,9 +7,14 @@ net.sf.jopt-simple:jopt-simple:5.0.4=jmh,jmhCompileClasspath,jmhImplementationDe
 org.apache.commons:commons-math3:3.6.1=jmh,jmhCompileClasspath,jmhImplementationDependenciesMetadata,jmhRuntimeClasspath
 org.apiguardian:apiguardian-api:1.1.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeOnlyDependenciesMetadata
 org.assertj:assertj-core:3.27.2=testCompileClasspath,testImplementationDependenciesMetadata,testRuntimeClasspath
-org.graalvm.compiler:compiler:23.0.6=graal
-org.graalvm.sdk:graal-sdk:23.0.6=graal,jmh,jmhRuntimeClasspath,truffle
-org.graalvm.truffle:truffle-api:23.0.6=graal,jmh,jmhRuntimeClasspath,truffle
+org.graalvm.compiler:compiler:24.1.2=graal
+org.graalvm.polyglot:polyglot:24.1.2=jmh,jmhRuntimeClasspath,truffle
+org.graalvm.sdk:collections:24.1.2=graal,jmh,jmhRuntimeClasspath,truffle
+org.graalvm.sdk:graal-sdk:24.1.2=jmh,jmhRuntimeClasspath
+org.graalvm.sdk:nativeimage:24.1.2=jmh,jmhRuntimeClasspath,truffle
+org.graalvm.sdk:word:24.1.2=graal,jmh,jmhRuntimeClasspath,truffle
+org.graalvm.truffle:truffle-api:24.1.2=jmh,jmhRuntimeClasspath,truffle
+org.graalvm.truffle:truffle-compiler:24.1.2=graal
 org.jetbrains.intellij.deps:trove4j:1.0.20200330=kotlinBuildToolsApiClasspath,kotlinCompilerClasspath,kotlinKlibCommonizerClasspath
 org.jetbrains.kotlin:kotlin-build-common:2.0.21=kotlinBuildToolsApiClasspath
 org.jetbrains.kotlin:kotlin-build-tools-api:2.0.21=kotlinBuildToolsApiClasspath

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