Gradle: Replace legacy buildSrc mechanism with included build (#1524)

Motivation:
buildSrc is a special-case legacy mechanism.
Gradle recommends using an included build named build-logic instead:

https://docs.gradle.org/current/userguide/best_practices_structuring_builds.html#favor_composite_builds

Changes:
- Rename buildSrc/ to build-logic/
  - triggers reformatting
- Replace occurrences of "buildSrc" with "build-logic"
- Include the build-logic build in the main build (via
settings.gradle.kts)
- Apply convention plugins via plugin IDs instead of type-safe accessors
  - small tradeoff compared to buildSrc

Result:
- Faster and more isolated builds
- Build logic behaves like a normal build, making it easier to evolve
and reason about

---------

Co-authored-by: Daniel Chao <dan.chao@apple.com>

bench/bench.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,8 +14,8 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklJavaLibrary
+  id("pklAllProjects")
+  id("pklJavaLibrary")
   id("me.champeau.jmh")
 }
 

build-logic/settings.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.
@@ -15,7 +15,7 @@
  */
 @file:Suppress("UnstableApiUsage")
 
-rootProject.name = "buildSrc"
+rootProject.name = "build-logic"
 
 pluginManagement {
   repositories {
@@ -24,7 +24,7 @@ pluginManagement {
   }
 }
 
-plugins { id("org.gradle.toolchains.foojay-resolver-convention") }
+plugins { id("org.gradle.toolchains.foojay-resolver-convention") version "1.0.0" }
 
 // makes ~/.gradle/init.gradle unnecessary and ~/.gradle/gradle.properties optional
 dependencyResolutionManagement {

build-logic/src/main/kotlin/BuildInfo.kt

@@ -44,7 +44,7 @@ const val PKL_JVM_TARGET_DEFAULT_MAXIMUM = 17
  *
  * This is a build-time requirement, not a runtime requirement. To avoid the provisioning of
  * multiple JDKs and other build issues, keep this value in sync with the JVM toolchain versions in
- * `buildSrc/build.gradle.kts` and `gradle-daemon-jvm.properties`.
+ * `build-logic/build.gradle.kts` and `gradle-daemon-jvm.properties`.
  */
 const val PKL_JDK_VERSION_MIN = 25
 

build-logic/src/main/kotlin/ExecutableSpec.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2025-2026 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.

build-logic/src/main/kotlin/GradlePluginTests.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.

build-logic/src/main/kotlin/GradleVersionInfo.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.

build-logic/src/main/kotlin/HtmlValidator.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.

build-logic/src/main/kotlin/InstallGraalVm.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.

build-logic/src/main/kotlin/NativeImageBuild.kt

@@ -55,13 +55,12 @@ abstract class NativeImageBuild : DefaultTask() {
 
   @get:Inject protected abstract val execOperations: ExecOperations
 
-  private val graalVm: Provider<BuildInfo.GraalVm> =
-    arch.map { a ->
-      when (a) {
-        Architecture.AMD64 -> buildInfo.graalVmAmd64
-        Architecture.AARCH64 -> buildInfo.graalVmAarch64
-      }
+  private val graalVm: Provider<BuildInfo.GraalVm> = arch.map { a ->
+    when (a) {
+      Architecture.AMD64 -> buildInfo.graalVmAmd64
+      Architecture.AARCH64 -> buildInfo.graalVmAarch64
     }
+  }
 
   private val buildInfo: BuildInfo = project.extensions.getByType(BuildInfo::class.java)
 
@@ -151,10 +150,9 @@ abstract class NativeImageBuild : DefaultTask() {
         }
         // native-image rejects non-existing class path entries -> filter
         add("--class-path")
-        val pathInput =
-          classpath.filter {
-            it.exists() && !exclusions.any { exclude -> it.name.contains(exclude) }
-          }
+        val pathInput = classpath.filter {
+          it.exists() && !exclusions.any { exclude -> it.name.contains(exclude) }
+        }
         add(pathInput.asPath)
         // make sure dev machine stays responsive (15% slowdown on my laptop)
         val processors =

build-logic/src/main/kotlin/PklPublishing.kt

@@ -63,59 +63,58 @@ fun Project.configurePklPomMetadata() {
 
 /** Configures POM validation task to check for unresolved versions and snapshots in releases. */
 fun Project.configurePomValidation() {
-  val validatePom by
-    tasks.registering {
-      if (tasks.findByName("generatePomFileForLibraryPublication") == null) {
-        return@registering
-      }
-      val generatePomFileForLibraryPublication by tasks.existing(GenerateMavenPom::class)
-      val outputFile =
-        layout.buildDirectory.file("validatePom") // dummy output to satisfy up-to-date check
+  val validatePom by tasks.registering {
+    if (tasks.findByName("generatePomFileForLibraryPublication") == null) {
+      return@registering
+    }
+    val generatePomFileForLibraryPublication by tasks.existing(GenerateMavenPom::class)
+    val outputFile =
+      layout.buildDirectory.file("validatePom") // dummy output to satisfy up-to-date check
 
-      dependsOn(generatePomFileForLibraryPublication)
-      inputs.file(generatePomFileForLibraryPublication.get().destination)
-      outputs.file(outputFile)
+    dependsOn(generatePomFileForLibraryPublication)
+    inputs.file(generatePomFileForLibraryPublication.get().destination)
+    outputs.file(outputFile)
 
-      doLast {
-        outputFile.get().asFile.delete()
+    doLast {
+      outputFile.get().asFile.delete()
 
-        val pomFile = generatePomFileForLibraryPublication.get().destination
-        assert(pomFile.exists())
+      val pomFile = generatePomFileForLibraryPublication.get().destination
+      assert(pomFile.exists())
 
-        val text = pomFile.readText()
+      val text = pomFile.readText()
 
-        run {
-          val unresolvedVersion = Regex("<version>.*[+,()\\[\\]].*</version>")
-          val matches = unresolvedVersion.findAll(text).toList()
-          if (matches.isNotEmpty()) {
-            throw org.gradle.api.GradleException(
-              """
+      run {
+        val unresolvedVersion = Regex("<version>.*[+,()\\[\\]].*</version>")
+        val matches = unresolvedVersion.findAll(text).toList()
+        if (matches.isNotEmpty()) {
+          throw org.gradle.api.GradleException(
+            """
         Found unresolved version selector(s) in generated POM:
         ${matches.joinToString("\n") { it.groupValues[0] }}
       """
-                .trimIndent()
-            )
-          }
+              .trimIndent()
+          )
         }
+      }
 
-        val buildInfo = project.extensions.getByType<BuildInfo>()
-        if (buildInfo.isReleaseBuild) {
-          val snapshotVersion = Regex("<version>.*-SNAPSHOT</version>")
-          val matches = snapshotVersion.findAll(text).toList()
-          if (matches.isNotEmpty()) {
-            throw org.gradle.api.GradleException(
-              """
+      val buildInfo = project.extensions.getByType<BuildInfo>()
+      if (buildInfo.isReleaseBuild) {
+        val snapshotVersion = Regex("<version>.*-SNAPSHOT</version>")
+        val matches = snapshotVersion.findAll(text).toList()
+        if (matches.isNotEmpty()) {
+          throw org.gradle.api.GradleException(
+            """
         Found snapshot version(s) in generated POM of Pkl release version:
         ${matches.joinToString("\n") { it.groupValues[0] }}
       """
-                .trimIndent()
-            )
-          }
+              .trimIndent()
+          )
         }
-
-        outputFile.get().asFile.writeText("OK")
       }
+
+      outputFile.get().asFile.writeText("OK")
     }
+  }
 
   tasks.named("publish") { dependsOn(validatePom) }
 }

build-logic/src/main/kotlin/ResolveSourcesJars.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.

build-logic/src/main/kotlin/pklAllProjects.gradle.kts

@@ -112,7 +112,7 @@ tasks.withType(JavaExec::class).configureEach {
 private val libs = the<LibrariesForLibs>()
 
 private val licenseHeaderFile by lazy {
-  rootProject.file("buildSrc/src/main/resources/license-header.star-block.txt")
+  rootProject.file("build-logic/src/main/resources/license-header.star-block.txt")
 }
 
 private fun KotlinGradleExtension.configureFormatter() {
@@ -136,18 +136,18 @@ spotless {
   val revertYearOnlyChangesStep =
     RevertYearOnlyChangesStep(rootProject.rootDir, ratchetFrom!!).create()
 
-  // When building root project, format buildSrc files too.
-  // We need this because buildSrc is not a subproject of the root project, so a top-level
-  // `spotlessApply` will not trigger `buildSrc:spotlessApply`.
-  if (project === rootProject) {
+  // When building root project, format build-logic files too.
+  // We need this because build-logic is not a subproject of the root project, so a top-level
+  // `spotlessApply` will not trigger `build-logic:spotlessApply`.
+  if (project.path == rootProject.path) {
     kotlinGradle {
       configureFormatter()
       addStep(revertYearOnlyChangesStep)
-      target("*.kts", "buildSrc/*.kts", "buildSrc/src/*/kotlin/**/*.kts")
+      target("*.kts", "build-logic/*.kts", "build-logic/src/*/kotlin/**/*.kts")
     }
     kotlin {
       ktfmt(libs.versions.ktfmt.get()).googleStyle()
-      target("buildSrc/src/*/kotlin/**/*.kt")
+      target("build-logic/src/*/kotlin/**/*.kt")
       licenseHeaderFile(licenseHeaderFile)
       addStep(revertYearOnlyChangesStep)
     }

build-logic/src/main/kotlin/pklGraalVm.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.

build-logic/src/main/kotlin/pklJavaExecutable.gradle.kts

@@ -47,20 +47,19 @@ fun Task.setupTestStartJavaExecutable(launcher: Provider<JavaLauncher>? = null)
   val outputFile = layout.buildDirectory.file("testStartJavaExecutable/$name")
   outputs.file(outputFile)
 
-  val execOutput =
-    providers.exec {
-      val executablePath = javaExecutable.get().outputs.files.singleFile
-      if (launcher?.isPresent == true) {
-        commandLine(
-          launcher.get().executablePath.asFile.absolutePath,
-          "-jar",
-          executablePath.absolutePath,
-          "--version",
-        )
-      } else {
-        commandLine(executablePath.absolutePath, "--version")
-      }
+  val execOutput = providers.exec {
+    val executablePath = javaExecutable.get().outputs.files.singleFile
+    if (launcher?.isPresent == true) {
+      commandLine(
+        launcher.get().executablePath.asFile.absolutePath,
+        "-jar",
+        executablePath.absolutePath,
+        "--version",
+      )
+    } else {
+      commandLine(executablePath.absolutePath, "--version")
     }
+  }
 
   doLast {
     val outputText = execOutput.standardOutput.asText.get()

build-logic/src/main/kotlin/pklJavaLibrary.gradle.kts

@@ -56,7 +56,9 @@ spotless {
     addStep(revertYearOnlyChanges)
     googleJavaFormat(libs.versions.googleJavaFormat.get())
     target("src/*/java/**/*.java")
-    licenseHeaderFile(rootProject.file("buildSrc/src/main/resources/license-header.star-block.txt"))
+    licenseHeaderFile(
+      rootProject.file("build-logic/src/main/resources/license-header.star-block.txt")
+    )
   }
 }
 

build-logic/src/main/kotlin/pklKotlinBase.gradle.kts

@@ -56,7 +56,9 @@ spotless {
     addStep(revertYearOnlyChanges)
     ktfmt(libs.versions.ktfmt.get()).googleStyle()
     target("src/*/kotlin/**/*.kt")
-    licenseHeaderFile(rootProject.file("buildSrc/src/main/resources/license-header.star-block.txt"))
+    licenseHeaderFile(
+      rootProject.file("build-logic/src/main/resources/license-header.star-block.txt")
+    )
   }
 }
 

build-logic/src/main/kotlin/pklNativeExecutable.gradle.kts

@@ -37,16 +37,15 @@ val stagedLinuxAarch64Executable: Configuration by configurations.creating
 val stagedAlpineLinuxAmd64Executable: Configuration by configurations.creating
 val stagedWindowsAmd64Executable: Configuration by configurations.creating
 
-val nativeImageClasspath by
-  configurations.creating {
-    extendsFrom(configurations.runtimeClasspath.get())
-    // Ensure native-image version uses GraalVM C SDKs instead of Java FFI or JNA
-    // (comes from artifact `mordant-jvm-graal-ffi`).
-    exclude("com.github.ajalt.mordant", "mordant-jvm-ffm")
-    exclude("com.github.ajalt.mordant", "mordant-jvm-ffm-jvm")
-    exclude("com.github.ajalt.mordant", "mordant-jvm-jna")
-    exclude("com.github.ajalt.mordant", "mordant-jvm-jna-jvm")
-  }
+val nativeImageClasspath by configurations.creating {
+  extendsFrom(configurations.runtimeClasspath.get())
+  // Ensure native-image version uses GraalVM C SDKs instead of Java FFI or JNA
+  // (comes from artifact `mordant-jvm-graal-ffi`).
+  exclude("com.github.ajalt.mordant", "mordant-jvm-ffm")
+  exclude("com.github.ajalt.mordant", "mordant-jvm-ffm-jvm")
+  exclude("com.github.ajalt.mordant", "mordant-jvm-jna")
+  exclude("com.github.ajalt.mordant", "mordant-jvm-jna-jvm")
+}
 
 val libs = the<LibrariesForLibs>()
 
@@ -140,65 +139,63 @@ val windowsExecutableAmd64 by
 
 val assembleNative by tasks.existing
 
-val testStartNativeExecutable by
-  tasks.registering {
-    dependsOn(assembleNative)
+val testStartNativeExecutable by tasks.registering {
+  dependsOn(assembleNative)
 
-    // dummy file for up-to-date checking
-    val outputFile = project.layout.buildDirectory.file("testStartNativeExecutable/output.txt")
-    outputs.file(outputFile)
+  // dummy file for up-to-date checking
+  val outputFile = project.layout.buildDirectory.file("testStartNativeExecutable/output.txt")
+  outputs.file(outputFile)
 
-    val execOutput =
-      providers.exec { commandLine(assembleNative.get().outputs.files.singleFile, "--version") }
+  val execOutput = providers.exec {
+    commandLine(assembleNative.get().outputs.files.singleFile, "--version")
+  }
 
-    doLast {
-      val outputText = execOutput.standardOutput.asText.get()
-      if (!outputText.contains(buildInfo.pklVersionNonUnique)) {
-        throw GradleException(
-          "Expected version output to contain current version (${buildInfo.pklVersionNonUnique}), but got '$outputText'"
-        )
-      }
-      outputFile.get().asFile.toPath().apply {
-        try {
-          parent.createDirectories()
-        } catch (_: java.nio.file.FileAlreadyExistsException) {}
-        writeText("OK")
-      }
+  doLast {
+    val outputText = execOutput.standardOutput.asText.get()
+    if (!outputText.contains(buildInfo.pklVersionNonUnique)) {
+      throw GradleException(
+        "Expected version output to contain current version (${buildInfo.pklVersionNonUnique}), but got '$outputText'"
+      )
+    }
+    outputFile.get().asFile.toPath().apply {
+      try {
+        parent.createDirectories()
+      } catch (_: java.nio.file.FileAlreadyExistsException) {}
+      writeText("OK")
     }
   }
+}
 
 val requiredGlibcVersion: Version = Version.parse("2.17")
 
-val checkGlibc by
-  tasks.registering {
-    enabled = buildInfo.os.isLinux && !buildInfo.musl
-    dependsOn(assembleNative)
-    doLast {
-      val exec =
-        providers.exec {
-          commandLine("objdump", "-T", assembleNative.get().outputs.files.singleFile)
+val checkGlibc by tasks.registering {
+  enabled = buildInfo.os.isLinux && !buildInfo.musl
+  dependsOn(assembleNative)
+  doLast {
+    val exec = providers.exec {
+      commandLine("objdump", "-T", assembleNative.get().outputs.files.singleFile)
+    }
+    val output = exec.standardOutput.asText.get()
+    val minimumGlibcVersion =
+      output
+        .split("\n")
+        .mapNotNull { line ->
+          val match = Regex("GLIBC_([.0-9]*)").find(line)
+          match?.groups[1]?.let { Version.parse(it.value) }
         }
-      val output = exec.standardOutput.asText.get()
-      val minimumGlibcVersion =
-        output
-          .split("\n")
-          .mapNotNull { line ->
-            val match = Regex("GLIBC_([.0-9]*)").find(line)
-            match?.groups[1]?.let { Version.parse(it.value) }
-          }
-          .maxOrNull()
-      if (minimumGlibcVersion == null) {
-        throw GradleException(
-          "Could not determine glibc version from executable. objdump output: $output"
-        )
-      }
-      if (minimumGlibcVersion > requiredGlibcVersion) {
-        throw GradleException(
-          "Incorrect glibc version. Found: $minimumGlibcVersion, required: $requiredGlibcVersion"
-        )
-      }
+        .maxOrNull()
+    if (minimumGlibcVersion == null) {
+      throw GradleException(
+        "Could not determine glibc version from executable. objdump output: $output"
+      )
+    }
+    if (minimumGlibcVersion > requiredGlibcVersion) {
+      throw GradleException(
+        "Incorrect glibc version. Found: $minimumGlibcVersion, required: $requiredGlibcVersion"
+      )
     }
   }
+}
 
 // Expose underlying task's outputs
 private fun <T : Task> Task.wraps(other: TaskProvider<T>) {

build-logic/src/main/kotlin/pklNativeLifecycle.gradle.kts

@@ -0,0 +1,122 @@
+/*
+ * Copyright © 2024-2026 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.
+ */
+val assembleNativeMacOsAarch64 by tasks.registering { group = "build" }
+
+val assembleNativeMacOsAmd64 by tasks.registering { group = "build" }
+
+val assembleNativeLinuxAarch64 by tasks.registering { group = "build" }
+
+val assembleNativeLinuxAmd64 by tasks.registering { group = "build" }
+
+val assembleNativeAlpineLinuxAmd64 by tasks.registering { group = "build" }
+
+val assembleNativeWindowsAmd64 by tasks.registering { group = "build" }
+
+val testNativeMacOsAarch64 by tasks.registering { group = "verification" }
+
+val testNativeMacOsAmd64 by tasks.registering { group = "verification" }
+
+val testNativeLinuxAarch64 by tasks.registering { group = "verification" }
+
+val testNativeLinuxAmd64 by tasks.registering { group = "verification" }
+
+val testNativeAlpineLinuxAmd64 by tasks.registering { group = "verification" }
+
+val testNativeWindowsAmd64 by tasks.registering { group = "verification" }
+
+val buildInfo = project.extensions.getByType<BuildInfo>()
+
+private fun <T : Task> Task.wraps(other: TaskProvider<T>) {
+  dependsOn(other)
+  outputs.files(other)
+}
+
+val assembleNative by tasks.registering {
+  group = "build"
+
+  if (!buildInfo.isCrossArchSupported && buildInfo.isCrossArch) {
+    throw GradleException("Cross-arch builds are not supported on ${buildInfo.os.name}")
+  }
+
+  when {
+    buildInfo.os.isMacOsX && buildInfo.targetArch == "aarch64" -> {
+      wraps(assembleNativeMacOsAarch64)
+    }
+    buildInfo.os.isMacOsX && buildInfo.targetArch == "amd64" -> {
+      wraps(assembleNativeMacOsAmd64)
+    }
+    buildInfo.os.isLinux && buildInfo.targetArch == "aarch64" -> {
+      wraps(assembleNativeLinuxAarch64)
+    }
+    buildInfo.os.isLinux && buildInfo.targetArch == "amd64" -> {
+      if (buildInfo.musl) wraps(assembleNativeAlpineLinuxAmd64) else wraps(assembleNativeLinuxAmd64)
+    }
+    buildInfo.os.isWindows && buildInfo.targetArch == "amd64" -> {
+      wraps(assembleNativeWindowsAmd64)
+    }
+    else -> {
+      doLast {
+        throw GradleException(
+          "Cannot build targeting ${buildInfo.os.name}/${buildInfo.targetArch} with musl=${buildInfo.musl}"
+        )
+      }
+    }
+  }
+}
+
+val testNative by tasks.registering {
+  group = "verification"
+  dependsOn(assembleNative)
+
+  if (!buildInfo.isCrossArchSupported && buildInfo.isCrossArch) {
+    throw GradleException("Cross-arch builds are not supported on ${buildInfo.os.name}")
+  }
+
+  when {
+    buildInfo.os.isMacOsX && buildInfo.targetArch == "aarch64" -> {
+      dependsOn(testNativeMacOsAarch64)
+    }
+    buildInfo.os.isMacOsX && buildInfo.targetArch == "amd64" -> {
+      dependsOn(testNativeMacOsAmd64)
+    }
+    buildInfo.os.isLinux && buildInfo.targetArch == "aarch64" -> {
+      dependsOn(testNativeLinuxAarch64)
+    }
+    buildInfo.os.isLinux && buildInfo.targetArch == "amd64" -> {
+      if (buildInfo.musl) dependsOn(testNativeAlpineLinuxAmd64) else dependsOn(testNativeLinuxAmd64)
+    }
+    buildInfo.os.isWindows && buildInfo.targetArch == "amd64" -> {
+      dependsOn(testNativeWindowsAmd64)
+    }
+    else -> {
+      doLast {
+        throw GradleException(
+          "Cannot build targeting ${buildInfo.os.name}/${buildInfo.targetArch} with musl=${buildInfo.musl}"
+        )
+      }
+    }
+  }
+}
+
+val checkNative by tasks.registering {
+  group = "verification"
+  dependsOn(testNative)
+}
+
+val buildNative by tasks.registering {
+  group = "build"
+  dependsOn(checkNative)
+}

build-logic/src/main/kotlin/pklSpotlessFormat.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2025-2026 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,7 +24,7 @@ spotless {
     target("**/*.pkl")
     addStep(PklFormatterStep(pklFormatter).create())
     licenseHeaderFile(
-      rootProject.file("buildSrc/src/main/resources/license-header.line-comment.txt"),
+      rootProject.file("build-logic/src/main/resources/license-header.line-comment.txt"),
       "/// ",
     )
     // disable ratcheting for Pkl sources

build.gradle.kts

@@ -19,8 +19,8 @@ import org.jetbrains.gradle.ext.ActionDelegationConfig.TestRunner.PLATFORM
 import org.jetbrains.gradle.ext.ProjectSettings
 
 plugins {
-  pklAllProjects
-  pklGraalVm
+  id("pklAllProjects")
+  id("pklGraalVm")
 
   alias(libs.plugins.ideaExt)
   alias(libs.plugins.jmh) apply false

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

@@ -1,128 +0,0 @@
-/*
- * 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.
- */
-val assembleNativeMacOsAarch64 by tasks.registering { group = "build" }
-
-val assembleNativeMacOsAmd64 by tasks.registering { group = "build" }
-
-val assembleNativeLinuxAarch64 by tasks.registering { group = "build" }
-
-val assembleNativeLinuxAmd64 by tasks.registering { group = "build" }
-
-val assembleNativeAlpineLinuxAmd64 by tasks.registering { group = "build" }
-
-val assembleNativeWindowsAmd64 by tasks.registering { group = "build" }
-
-val testNativeMacOsAarch64 by tasks.registering { group = "verification" }
-
-val testNativeMacOsAmd64 by tasks.registering { group = "verification" }
-
-val testNativeLinuxAarch64 by tasks.registering { group = "verification" }
-
-val testNativeLinuxAmd64 by tasks.registering { group = "verification" }
-
-val testNativeAlpineLinuxAmd64 by tasks.registering { group = "verification" }
-
-val testNativeWindowsAmd64 by tasks.registering { group = "verification" }
-
-val buildInfo = project.extensions.getByType<BuildInfo>()
-
-private fun <T : Task> Task.wraps(other: TaskProvider<T>) {
-  dependsOn(other)
-  outputs.files(other)
-}
-
-val assembleNative by
-  tasks.registering {
-    group = "build"
-
-    if (!buildInfo.isCrossArchSupported && buildInfo.isCrossArch) {
-      throw GradleException("Cross-arch builds are not supported on ${buildInfo.os.name}")
-    }
-
-    when {
-      buildInfo.os.isMacOsX && buildInfo.targetArch == "aarch64" -> {
-        wraps(assembleNativeMacOsAarch64)
-      }
-      buildInfo.os.isMacOsX && buildInfo.targetArch == "amd64" -> {
-        wraps(assembleNativeMacOsAmd64)
-      }
-      buildInfo.os.isLinux && buildInfo.targetArch == "aarch64" -> {
-        wraps(assembleNativeLinuxAarch64)
-      }
-      buildInfo.os.isLinux && buildInfo.targetArch == "amd64" -> {
-        if (buildInfo.musl) wraps(assembleNativeAlpineLinuxAmd64)
-        else wraps(assembleNativeLinuxAmd64)
-      }
-      buildInfo.os.isWindows && buildInfo.targetArch == "amd64" -> {
-        wraps(assembleNativeWindowsAmd64)
-      }
-      else -> {
-        doLast {
-          throw GradleException(
-            "Cannot build targeting ${buildInfo.os.name}/${buildInfo.targetArch} with musl=${buildInfo.musl}"
-          )
-        }
-      }
-    }
-  }
-
-val testNative by
-  tasks.registering {
-    group = "verification"
-    dependsOn(assembleNative)
-
-    if (!buildInfo.isCrossArchSupported && buildInfo.isCrossArch) {
-      throw GradleException("Cross-arch builds are not supported on ${buildInfo.os.name}")
-    }
-
-    when {
-      buildInfo.os.isMacOsX && buildInfo.targetArch == "aarch64" -> {
-        dependsOn(testNativeMacOsAarch64)
-      }
-      buildInfo.os.isMacOsX && buildInfo.targetArch == "amd64" -> {
-        dependsOn(testNativeMacOsAmd64)
-      }
-      buildInfo.os.isLinux && buildInfo.targetArch == "aarch64" -> {
-        dependsOn(testNativeLinuxAarch64)
-      }
-      buildInfo.os.isLinux && buildInfo.targetArch == "amd64" -> {
-        if (buildInfo.musl) dependsOn(testNativeAlpineLinuxAmd64)
-        else dependsOn(testNativeLinuxAmd64)
-      }
-      buildInfo.os.isWindows && buildInfo.targetArch == "amd64" -> {
-        dependsOn(testNativeWindowsAmd64)
-      }
-      else -> {
-        doLast {
-          throw GradleException(
-            "Cannot build targeting ${buildInfo.os.name}/${buildInfo.targetArch} with musl=${buildInfo.musl}"
-          )
-        }
-      }
-    }
-  }
-
-val checkNative by
-  tasks.registering {
-    group = "verification"
-    dependsOn(testNative)
-  }
-
-val buildNative by
-  tasks.registering {
-    group = "build"
-    dependsOn(checkNative)
-  }

docs/docs.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,8 +16,8 @@
 import org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension
 
 plugins {
-  pklAllProjects
-  pklKotlinTest
+  id("pklAllProjects")
+  id("pklKotlinTest")
 }
 
 sourceSets {

pkl-bom/pkl-bom.gradle.kts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
+  id("pklAllProjects")
   `java-platform`
   `maven-publish`
   signing

pkl-cli/pkl-cli.gradle.kts

@@ -18,14 +18,14 @@ import java.io.OutputStream
 import org.gradle.kotlin.dsl.support.serviceOf
 
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklPublishLibrary
-  pklJavaExecutable
-  pklNativeExecutable
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklPublishLibrary")
+  id("pklJavaExecutable")
+  id("pklNativeExecutable")
   `maven-publish`
 
-  // already on build script class path (see buildSrc/build.gradle.kts),
+  // already on build script class path (see build-logic/build.gradle.kts),
   // hence must only specify plugin ID here
   id(libs.plugins.shadow.get().pluginId)
 

pkl-codegen-java/pkl-codegen-java.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,10 +14,10 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklPublishLibrary
-  pklJavaExecutable
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklPublishLibrary")
+  id("pklJavaExecutable")
 }
 
 dependencies {
@@ -56,7 +56,7 @@ publishing {
           """
           Java source code generator that generates corresponding Java classes for Pkl classes,
           simplifying consumption of Pkl configuration as statically typed Java objects.
-        """
+          """
             .trimIndent()
         )
       }

pkl-codegen-kotlin/pkl-codegen-kotlin.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,10 +14,10 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklPublishLibrary
-  pklJavaExecutable
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklPublishLibrary")
+  id("pklJavaExecutable")
 }
 
 publishing {
@@ -29,7 +29,7 @@ publishing {
           """
           Kotlin source code generator that generates corresponding Kotlin classes for Pkl classes,
           simplifying consumption of Pkl configuration as statically typed Kotlin objects.
-        """
+          """
             .trimIndent()
         )
       }

pkl-commons-cli/pkl-commons-cli.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,9 +14,9 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklPublishLibrary
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklPublishLibrary")
 }
 
 val svmClasspath: Configuration by configurations.creating

pkl-commons-test/pkl-commons-test.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,8 +16,8 @@
 import java.security.MessageDigest
 
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
 }
 
 // note: no need to publish this library

pkl-commons/pkl-commons.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,9 +14,9 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklPublishLibrary
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklPublishLibrary")
 }
 
 publishing {

pkl-config-java/pkl-config-java.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,10 +14,10 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklJavaLibrary
-  pklFatJar
-  pklPublishLibrary
+  id("pklAllProjects")
+  id("pklJavaLibrary")
+  id("pklFatJar")
+  id("pklPublishLibrary")
   signing
 }
 

pkl-config-kotlin/pkl-config-kotlin.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,9 +14,9 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklPublishLibrary
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklPublishLibrary")
 }
 
 val pklConfigJava: Configuration by configurations.creating

pkl-core/pkl-core.gradle.kts

@@ -17,10 +17,10 @@ import org.apache.tools.ant.filters.ReplaceTokens
 
 plugins {
   kotlin("jvm") // for `src/generator/kotlin`
-  pklAllProjects
-  pklJavaLibrary
-  pklPublishLibrary
-  pklNativeLifecycle
+  id("pklAllProjects")
+  id("pklJavaLibrary")
+  id("pklPublishLibrary")
+  id("pklNativeLifecycle")
   idea
 }
 

pkl-doc/pkl-doc.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,11 +14,11 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklJavaExecutable
-  pklNativeExecutable
-  pklHtmlValidator
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklJavaExecutable")
+  id("pklNativeExecutable")
+  id("pklHtmlValidator")
   alias(libs.plugins.kotlinxSerialization)
 }
 

pkl-executor/pkl-executor.gradle.kts

@@ -17,9 +17,9 @@ import java.nio.file.Files
 import java.nio.file.LinkOption
 
 plugins {
-  pklAllProjects
-  pklJavaLibrary
-  pklPublishLibrary
+  id("pklAllProjects")
+  id("pklJavaLibrary")
+  id("pklPublishLibrary")
 }
 
 val pklDistributionCurrent: Configuration by configurations.creating

pkl-formatter/pkl-formatter.gradle.kts

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklJavaLibrary
-  pklPublishLibrary
+  id("pklAllProjects")
+  id("pklJavaLibrary")
+  id("pklPublishLibrary")
 }
 
 dependencies {

pkl-gradle/pkl-gradle.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,13 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklJavaLibrary
-  pklGradlePluginTest
+  id("pklAllProjects")
+  id("pklJavaLibrary")
+  id("pklGradlePluginTest")
 
   `java-gradle-plugin`
   `maven-publish`
-  pklPublishLibrary
+  id("pklPublishLibrary")
   signing
 }
 

pkl-parser/pkl-parser.gradle.kts

@@ -14,10 +14,10 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklJavaLibrary
-  pklJSpecify
-  pklPublishLibrary
+  id("pklAllProjects")
+  id("pklJavaLibrary")
+  id("pklJSpecify")
+  id("pklPublishLibrary")
   idea
 }
 

pkl-server/pkl-server.gradle.kts

@@ -14,9 +14,9 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
-  pklKotlinLibrary
-  pklNativeLifecycle
+  id("pklAllProjects")
+  id("pklKotlinLibrary")
+  id("pklNativeLifecycle")
 }
 
 dependencies {

pkl-tools/pkl-tools.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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.
@@ -20,8 +20,8 @@ import kotlin.io.path.createDirectories
 import kotlin.io.path.writeText
 
 plugins {
-  pklAllProjects
-  pklFatJar
+  id("pklAllProjects")
+  id("pklFatJar")
   signing
 }
 

settings.gradle.kts

@@ -15,6 +15,8 @@
  */
 rootProject.name = "pkl"
 
+includeBuild("build-logic")
+
 include("bench")
 
 include("docs")

stdlib/stdlib.gradle.kts

@@ -1,5 +1,5 @@
 /*
- * Copyright © 2024-2025 Apple Inc. and the Pkl project authors. All rights reserved.
+ * Copyright © 2024-2026 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,11 +14,11 @@
  * limitations under the License.
  */
 plugins {
-  pklAllProjects
+  id("pklAllProjects")
   base
   `maven-publish`
-  pklPublishLibrary
-  pklSpotlessFormat
+  id("pklPublishLibrary")
+  id("pklSpotlessFormat")
   signing
 }