KTOR-7743 Create build-logic as a replacement for buildSrc (#4614)

* Create build-logic module, rename build-settings-logic for consistency
* Define the project version in base plugin
* Move dokka configuration to a precompiled script plugin
* Define the group in gradle.properties

build-logic/README.md

@@ -0,0 +1,22 @@
+# build-logic
+
+Build logic shared between Ktor subprojects.
+
+This is similar to `buildSrc`, but uses [composite builds](https://docs.gradle.org/current/userguide/composite_builds.html)
+to prevent projects from becoming out-of-date on any change in `buildSrc`.
+
+This project should be included in the root `settings.gradle.kts`:
+
+`<root project dir>/settings.gradle.kts`
+```kotlin
+includeBuild("build-logic")
+```
+
+`<root project dir>/build.gradle.kts`
+```kotlin
+plugins {
+    id("ktorbuild.base")
+}
+```
+
+*The structure of this project is inspired by the structure used in [Dokka](https://github.com/Kotlin/dokka/tree/v2.0.0/build-logic/src/main/kotlin) and [Gradle](https://github.com/gradle/gradle/tree/v8.12.0/build-logic/jvm/src/main/kotlin).*

build-logic/build.gradle.kts

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    `kotlin-dsl`
+}
+
+dependencies {
+    implementation(libs.kotlin.gradlePlugin)
+    implementation(libs.dokka.gradlePlugin)
+
+    // A hack to make version catalogs accessible from buildSrc sources
+    // https://github.com/gradle/gradle/issues/15383#issuecomment-779893192
+    implementation(files(libs.javaClass.superclass.protectionDomain.codeSource.location))
+}
+
+// Should be synced with gradle/gradle-daemon-jvm.properties
+kotlin {
+    jvmToolchain(21)
+}

build-logic/settings.gradle.kts

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+pluginManagement {
+    includeBuild("../build-settings-logic")
+}
+
+plugins {
+    id("conventions-dependency-resolution-management")
+}
+
+dependencyResolutionManagement {
+    // Additional repositories for build-logic
+    @Suppress("UnstableApiUsage")
+    repositories {
+        gradlePluginPortal()
+    }
+}
+
+rootProject.name = "build-logic"

build-logic/src/main/kotlin/ktorbuild.base.gradle.kts

@@ -0,0 +1,7 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import ktorbuild.internal.resolveVersion
+
+version = resolveVersion()

build-logic/src/main/kotlin/ktorbuild.dokka.gradle.kts

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+import ktorbuild.internal.libs
+import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+dependencies {
+    dokkaPlugin(libs.dokka.plugin.versioning)
+}
+
+if (project == rootProject) {
+    tasks.withType<DokkaMultiModuleTask>().configureEach {
+        val version = project.version
+        val dokkaOutputDir = "../versions"
+        val id = "org.jetbrains.dokka.versioning.VersioningPlugin"
+        val config = """{ "version": "$version", "olderVersionsDir":"$dokkaOutputDir" }"""
+
+        outputDirectory = project.layout.projectDirectory.dir("$dokkaOutputDir/$version")
+        pluginsMapConfiguration = mapOf(id to config)
+    }
+}

build-logic/src/main/kotlin/ktorbuild/internal/Version.kt

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package ktorbuild.internal
+
+import org.gradle.api.Project
+
+/**
+ * Resolves the version for the current project based on the defined properties.
+ * Properties "releaseVersion" and "eapVersion" are passed on CI as build parameters:
+ * ```
+ * ./gradlew build -PreleaseVersion=3.0.0
+ * ```
+ */
+internal fun Project.resolveVersion(): String {
+    val projectVersion = version.toString().removeSuffix("-SNAPSHOT")
+    val releaseVersion = findProperty("releaseVersion")?.toString()
+    val eapVersion = findProperty("eapVersion")?.toString()
+
+    return when {
+        releaseVersion != null -> releaseVersion
+        eapVersion != null -> "$projectVersion-eap-$eapVersion"
+        else -> projectVersion
+    }
+}

build-logic/src/main/kotlin/ktorbuild/internal/VersionCatalogs.kt

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package ktorbuild.internal
+
+import org.gradle.accessors.dm.LibrariesForLibs
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.the
+
+/**
+ * Accessor to make version catalog available in build-logic.
+ * See: https://github.com/gradle/gradle/issues/15383#issuecomment-779893192
+ */
+internal val Project.libs: LibrariesForLibs
+    get() = rootProject.the<LibrariesForLibs>()

gradle-settings-conventions/build.gradle.kts → build-settings-logic/build.gradle.kts

@@ -15,3 +15,8 @@ dependencies {
     implementation(libs.develocity)
     implementation(libs.develocity.commonCustomUserData)
 }
+
+// Should be synced with gradle/gradle-daemon-jvm.properties
+kotlin {
+    jvmToolchain(21)
+}

gradle-settings-conventions/settings.gradle.kts → build-settings-logic/settings.gradle.kts

@@ -10,4 +10,4 @@ dependencyResolutionManagement {
     }
 }
 
-rootProject.name = "gradle-settings-conventions"
+rootProject.name = "build-settings-logic"

build.gradle.kts

@@ -2,28 +2,13 @@
  * Copyright 2014-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
-import org.jetbrains.dokka.gradle.DokkaMultiModuleTask
 import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
 import org.jetbrains.kotlin.konan.target.HostManager
 
-val releaseVersion: String? by extra
-val eapVersion: String? by extra
-val version = (project.version as String).let { if (it.endsWith("-SNAPSHOT")) it.dropLast("-SNAPSHOT".length) else it }
-
-extra["configuredVersion"] = when {
-    releaseVersion != null -> releaseVersion
-    eapVersion != null -> "$version-eap-$eapVersion"
-    else -> project.version
-}
-
-println("The build version is ${extra["configuredVersion"]}")
-
 extra["globalM2"] = "${project.file("build")}/m2"
 extra["publishLocal"] = project.hasProperty("publishLocal")
 
-val configuredVersion: String by extra
-
 apply(from = "gradle/verifier.gradle")
 
 val internalProjects = listOf(
@@ -49,14 +34,16 @@ extra["nonDefaultProjectStructure"] = mutableListOf(
 apply(from = "gradle/compatibility.gradle")
 
 plugins {
-    alias(libs.plugins.dokka) apply false
+    id("ktorbuild.base")
     alias(libs.plugins.binaryCompatibilityValidator)
     conventions.gradleDoctor
 }
 
+println("Build version: ${project.version}")
+
 subprojects {
-    group = "io.ktor"
-    version = configuredVersion
+    apply(plugin = "ktorbuild.base")
+
     extra["hostManager"] = HostManager()
 
     setupTrainForSubproject()
@@ -98,23 +85,7 @@ filterSnapshotTests()
 
 fun configureDokka() {
     allprojects {
-        plugins.apply("org.jetbrains.dokka")
-
-        val dokkaPlugin by configurations
-        dependencies {
-            dokkaPlugin(rootProject.libs.dokka.plugin.versioning)
-        }
-    }
-
-    val dokkaOutputDir = "../versions"
-
-    tasks.withType<DokkaMultiModuleTask>().configureEach {
-        val id = "org.jetbrains.dokka.versioning.VersioningPlugin"
-        val config = """{ "version": "$configuredVersion", "olderVersionsDir":"$dokkaOutputDir" }"""
-        val mapOf = mapOf(id to config)
-
-        outputDirectory.set(file(projectDir.toPath().resolve(dokkaOutputDir).resolve(configuredVersion)))
-        pluginsMapConfiguration.set(mapOf)
+        plugins.apply("ktorbuild.dokka")
     }
 
     rootProject.plugins.withType<org.jetbrains.kotlin.gradle.targets.js.yarn.YarnPlugin> {

buildSrc/settings.gradle.kts

@@ -3,7 +3,7 @@
  */
 
 pluginManagement {
-    includeBuild("../gradle-settings-conventions")
+    includeBuild("../build-settings-logic")
 }
 
 plugins {

buildSrc/src/main/kotlin/JvmConfig.kt

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
+ * Copyright 2014-2025 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
 import internal.libs
@@ -71,15 +71,13 @@ fun Project.configureJvm() {
         configureJavaToolchain(compileJdk, testJdk)
     }
 
-    val configuredVersion: String by rootProject.extra
     tasks.named<Jar>("jvmJar") {
         manifest {
             attributes(
-                "Implementation-Title" to name,
-                "Implementation-Version" to configuredVersion
+                "Implementation-Title" to project.name,
+                "Implementation-Version" to project.version,
+                "Automatic-Module-Name" to project.javaModuleName(),
             )
-            val name = project.javaModuleName()
-            attributes("Automatic-Module-Name" to name)
         }
     }
 }

gradle.properties

@@ -6,6 +6,7 @@
 kotlin.code.style=official
 
 # config
+group=io.ktor
 version=3.1.0-SNAPSHOT
 
 ## Performance

gradle/libs.versions.toml

@@ -128,6 +128,7 @@ kotlinx-io-core = { module = "org.jetbrains.kotlinx:kotlinx-io-core", version.re
 
 kotlinx-browser = { module = "org.jetbrains.kotlinx:kotlinx-browser", version.ref = "kotlinx-browser" }
 
+dokka-gradlePlugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" }
 dokka-plugin-versioning = { module = "org.jetbrains.dokka:versioning-plugin", version.ref = "dokka" }
 
 netty-handler = { module = "io.netty:netty-handler", version.ref = "netty" }
@@ -233,7 +234,6 @@ gradleDoctor = { module = "com.osacky.doctor:doctor-plugin", version.ref = "grad
 [plugins]
 
 binaryCompatibilityValidator = { id = "org.jetbrains.kotlinx.binary-compatibility-validator", version.ref = "binaryCompatibilityValidator" }
-dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }
 kover = { id = "org.jetbrains.kotlinx.kover", version.ref = "kover" }
 
 doctor = { id = "com.osacky.doctor", version.ref = "gradleDoctor" }

ktor-server/ktor-server-plugins/ktor-server-default-headers/build.gradle.kts

@@ -2,7 +2,7 @@
  * Copyright 2014-2024 JetBrains s.r.o and contributors. Use of this source code is governed by the Apache 2.0 license.
  */
 
-import java.time.*
+import java.time.Year
 
 description = ""
 
@@ -16,10 +16,8 @@ kotlin {
     }
 }
 
-val configuredVersion: String by rootProject.extra
-
 val generateKtorVersionFile by tasks.registering {
-    val ktorVersion = configuredVersion
+    val ktorVersion = project.version
     inputs.property("ktor_version", ktorVersion)
 
     val year = Year.now().toString()

ktor-test-server/settings.gradle.kts

@@ -3,7 +3,7 @@
  */
 
 pluginManagement {
-    includeBuild("../gradle-settings-conventions")
+    includeBuild("../build-settings-logic")
 }
 
 plugins {

settings.gradle.kts

@@ -3,7 +3,7 @@
  */
 
 pluginManagement {
-    includeBuild("gradle-settings-conventions")
+    includeBuild("build-settings-logic")
 }
 
 plugins {
@@ -14,6 +14,7 @@ plugins {
 
 rootProject.name = "ktor"
 
+includeBuild("build-logic")
 includeBuild("ktor-test-server")
 
 include(":ktor-server")