Merge remote-tracking branch 'origin/master' into KT-64377/java-test-…

…suites

CONTRIBUTING.md

@@ -154,6 +154,22 @@ Notable builds:
   runs Dokka's integration tests, which are designed to test compatibility with different Kotlin versions, with different
   multiplatform targets and with various user scenarios.
 
+### Gradle Build Scans
+
+[Gradle Build Scans](https://scans.gradle.com/) can provide insights into a Dokka Build. 
+JetBrains runs a [Gradle Develocity server](https://ge.jetbrains.com/scans?search.rootProjectNames=dokka).
+that can be used to automatically upload reports.
+
+To automatically opt in add the following to `$GRADLE_USER_HOME/gradle.properties`. 
+
+```properties
+org.jetbrains.dokka.build.scan.url=https\://ge.jetbrains.com/
+# optionally provide a username that will be attached to each report
+org.jetbrains.dokka.build.scan.username=Hannah Clarke
+```
+
+A Build Scan may contain identifiable information. See the Terms of Use https://gradle.com/legal/terms-of-use/.
+
 ## Contacting maintainers
 
 * If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues).

build-settings-logic/build.gradle.kts

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+plugins {
+    `kotlin-dsl`
+}
+
+description = "Conventions for use in settings.gradle.kts scripts"
+
+dependencies {
+    implementation(libs.gradlePlugin.gradle.enterprise)
+    implementation(libs.gradlePlugin.gradle.customUserData)
+}

build-settings-logic/settings.gradle.kts

@@ -0,0 +1,29 @@
+import org.gradle.api.initialization.resolve.RepositoriesMode.PREFER_SETTINGS
+
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+rootProject.name = "build-settings-logic"
+
+pluginManagement {
+    repositories {
+        mavenCentral()
+        gradlePluginPortal()
+    }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+    repositoriesMode.set(PREFER_SETTINGS)
+    repositories {
+        mavenCentral()
+        gradlePluginPortal()
+    }
+
+    versionCatalogs {
+        create("libs") {
+            from(files("../gradle/libs.versions.toml"))
+        }
+    }
+}

build-settings-logic/src/main/kotlin/DokkaBuildSettingsProperties.kt

@@ -0,0 +1,70 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+import org.gradle.api.initialization.Settings
+import org.gradle.api.provider.Provider
+import org.gradle.api.provider.ProviderFactory
+import org.gradle.kotlin.dsl.create
+import org.gradle.kotlin.dsl.findByType
+import javax.inject.Inject
+
+/**
+ * Shared properties in `settings.gradle.kts` files.
+ *
+ * Fetch an instance using [DokkaBuildSettingsProperties.Companion.dokkaBuildSettingsProperties].
+ */
+abstract class DokkaBuildSettingsProperties @Inject constructor(
+    private val providers: ProviderFactory
+) {
+    val buildingOnTeamCity: Boolean = System.getenv("TEAMCITY_VERSION") != null
+    val buildingOnCi: Boolean = System.getenv("CI") != null || buildingOnTeamCity
+
+
+    //region Gradle Build Scan
+    // NOTE: build scan properties are documented in CONTRIBUTING.md
+    /** If unset, the user has not opted in to publish Build Scans. */
+    val buildScanUrl: Provider<String> =
+        dokkaProperty("build.scan.url")
+
+    /** Optionally override the default name attached to a Build Scan. */
+    val buildScanUsername: Provider<String> =
+        dokkaProperty("build.scan.username")
+            .orElse(BUILD_SCAN_USERNAME_DEFAULT)
+            .map(String::trim)
+    //endregion
+
+
+    //region Gradle Build Cache
+    val buildCacheLocalEnabled: Provider<Boolean> =
+        dokkaProperty("build.cache.local.enabled", String::toBoolean)
+            .orElse(!buildingOnCi)
+    val buildCacheLocalDirectory: Provider<String> =
+        dokkaProperty("build.cache.local.directory")
+    val buildCacheUrl: Provider<String> =
+        dokkaProperty("build.cache.url").map(String::trim)
+    val buildCachePushEnabled: Provider<Boolean> =
+        dokkaProperty("build.cache.push", String::toBoolean)
+            .orElse(buildingOnTeamCity)
+    val buildCacheUser: Provider<String> =
+        dokkaProperty("build.cache.user")
+    val buildCachePassword: Provider<String> =
+        dokkaProperty("build.cache.password")
+    //endregion
+
+
+    private fun dokkaProperty(name: String): Provider<String> =
+        providers.gradleProperty("org.jetbrains.dokka.$name")
+
+    private fun <T : Any> dokkaProperty(name: String, convert: (String) -> T): Provider<T> =
+        dokkaProperty(name).map(convert)
+
+    companion object {
+        const val BUILD_SCAN_USERNAME_DEFAULT = "<default>"
+
+        val Settings.dokkaBuildSettingsProperties: DokkaBuildSettingsProperties
+            get() {
+                return extensions.findByType<DokkaBuildSettingsProperties>()
+                    ?: extensions.create<DokkaBuildSettingsProperties>("dokkaBuildSettingsProperties")
+            }
+    }
+}

build-settings-logic/src/main/kotlin/dokkasettings.build-cache.settings.gradle.kts

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+import DokkaBuildSettingsProperties.Companion.dokkaBuildSettingsProperties
+
+/**
+ * Gradle Build Cache conventions.
+ *
+ * See [DokkaBuildSettingsProperties] for properties.
+ *
+ * Because Dokka uses Composite Builds, Build Cache should only be configured on the root `settings.gradle.kts`.
+ * See https://docs.gradle.org/8.4/userguide/build_cache.html#sec:build_cache_composite.
+ *
+ * Based on https://github.com/JetBrains/kotlin/blob/2675531624d42851af502a993bbefd65ee3e38ef/repo/gradle-settings-conventions/build-cache/src/main/kotlin/build-cache.settings.gradle.kts
+ */
+
+val buildSettingsProps = dokkaBuildSettingsProperties
+
+buildCache {
+    local {
+        isEnabled = buildSettingsProps.buildCacheLocalEnabled.get()
+        if (buildSettingsProps.buildCacheLocalDirectory.orNull != null) {
+            directory = buildSettingsProps.buildCacheLocalDirectory.get()
+        }
+    }
+
+    val remoteBuildCacheUrl = buildSettingsProps.buildCacheUrl.orNull
+    if (!remoteBuildCacheUrl.isNullOrEmpty()) {
+        remote<HttpBuildCache> {
+            url = uri(remoteBuildCacheUrl)
+            isPush = buildSettingsProps.buildCachePushEnabled.get()
+
+            if (buildSettingsProps.buildCacheUser.isPresent &&
+                buildSettingsProps.buildCachePassword.isPresent
+            ) {
+                credentials.username = buildSettingsProps.buildCacheUser.get()
+                credentials.password = buildSettingsProps.buildCachePassword.get()
+            }
+        }
+    }
+}

build-settings-logic/src/main/kotlin/dokkasettings.gradle-enterprise.settings.gradle.kts

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+import DokkaBuildSettingsProperties.Companion.BUILD_SCAN_USERNAME_DEFAULT
+import DokkaBuildSettingsProperties.Companion.dokkaBuildSettingsProperties
+
+/**
+ * Gradle Enterprise conventions.
+ *
+ * See [DokkaBuildSettingsProperties] for properties.
+ *
+ * To use JetBrain's Gradle Enterprise set the URL
+ * https://ge.jetbrains.com/
+ * in `$GRADLE_USER_HOME/gradle.properties`†
+ *
+ * ```properties
+ * org.jetbrains.dokka.build.scan.url=https\://ge.jetbrains.com/
+ * ```
+ *
+ * Based on https://github.com/JetBrains/kotlin/blob/19073b96a7ed53dbda61337465ca898c1482e090/repo/gradle-settings-conventions/gradle-enterprise/src/main/kotlin/gradle-enterprise.settings.gradle.kts
+ *
+ * † _See [`GRADLE_USER_HOME`](https://docs.gradle.org/8.5/userguide/directory_layout.html#dir:gradle_user_home)_
+ */
+
+plugins {
+    id("com.gradle.enterprise")
+    id("com.gradle.common-custom-user-data-gradle-plugin") apply false
+}
+
+val buildSettingsProps = dokkaBuildSettingsProperties
+
+val buildScanServer = buildSettingsProps.buildScanUrl.orNull?.ifBlank { null }
+
+if (buildScanServer != null) {
+    plugins.apply("com.gradle.common-custom-user-data-gradle-plugin")
+}
+
+gradleEnterprise {
+    buildScan {
+        if (buildScanServer != null) {
+            server = buildScanServer
+            publishAlways()
+
+            capture {
+                isTaskInputFiles = true
+                isBuildLogging = true
+                isUploadInBackground = true
+            }
+        }
+
+        val overriddenName = buildSettingsProps.buildScanUsername.orNull
+        obfuscation {
+            ipAddresses { _ -> listOf("0.0.0.0") }
+            hostname { _ -> "concealed" }
+            username { originalUsername ->
+                when {
+                    buildSettingsProps.buildingOnTeamCity -> "TeamCity"
+                    buildSettingsProps.buildingOnCi -> "CI"
+                    overriddenName.isNullOrBlank() -> overriddenName
+                    overriddenName == BUILD_SCAN_USERNAME_DEFAULT -> originalUsername
+                    else -> "unknown"
+                }
+            }
+        }
+    }
+}

dokka-integration-tests/settings.gradle.kts

@@ -8,6 +8,7 @@ rootProject.name = "dokka-integration-tests"
 
 pluginManagement {
     includeBuild("../build-logic")
+    includeBuild("../build-settings-logic")
 
     repositories {
         mavenCentral()
@@ -17,6 +18,7 @@ pluginManagement {
 
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.7.0"
+    id("dokkasettings.gradle-enterprise")
 }
 
 dependencyResolutionManagement {

dokka-runners/runner-cli/settings.gradle.kts

@@ -8,6 +8,7 @@ rootProject.name = "runner-cli"
 
 pluginManagement {
     includeBuild("../../build-logic")
+    includeBuild("../../build-settings-logic")
 
     repositories {
         mavenCentral()
@@ -17,6 +18,7 @@ pluginManagement {
 
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.7.0"
+    id("dokkasettings.gradle-enterprise")
 }
 
 dependencyResolutionManagement {

dokka-runners/runner-gradle-plugin-classic/settings.gradle.kts

@@ -8,6 +8,7 @@ rootProject.name = "runner-gradle-plugin-classic"
 
 pluginManagement {
     includeBuild("../../build-logic")
+    includeBuild("../../build-settings-logic")
 
     repositories {
         mavenCentral()
@@ -17,6 +18,7 @@ pluginManagement {
 
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.7.0"
+    id("dokkasettings.gradle-enterprise")
 }
 
 dependencyResolutionManagement {

dokka-runners/runner-maven-plugin/settings.gradle.kts

@@ -8,6 +8,7 @@ rootProject.name = "runner-maven-plugin"
 
 pluginManagement {
     includeBuild("../../build-logic")
+    includeBuild("../../build-settings-logic")
 
     repositories {
         mavenCentral()
@@ -17,6 +18,7 @@ pluginManagement {
 
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.7.0"
+    id("dokkasettings.gradle-enterprise")
 }
 
 dependencyResolutionManagement {

gradle.properties

@@ -10,6 +10,8 @@ org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8
 org.jetbrains.dokka.kotlinLanguageLevel=1.4
 
+org.jetbrains.dokka.build.cache.url=https\://ge.jetbrains.com/cache/
+
 # Code style
 kotlin.code.style=official
 

gradle/libs.versions.toml

@@ -5,6 +5,8 @@ gradlePlugin-kotlin = "1.9.22"
 gradlePlugin-android = "4.2.2"
 gradlePlugin-android-dokkatoo = "8.0.2"
 gradlePlugin-dokka = "1.9.10"
+gradlePlugin-gradle-customUserData = "1.12"
+gradlePlugin-gradle-enterprise = "3.14.1"
 
 kotlinx-coroutines = "1.7.3"
 kotlinx-collections-immutable = "0.3.6"
@@ -63,6 +65,7 @@ eclipse-jgit = "5.13.2.202306221912-r" # jgit 6.X requires Java 11 to run
 
 [libraries]
 
+#### Kotlin Libs ####
 kotlinx-coroutines-core = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "kotlinx-coroutines" }
 kotlinx-collections-immutable = { module = "org.jetbrains.kotlinx:kotlinx-collections-immutable-jvm", version.ref = "kotlinx-collections-immutable" }
 kotlinx-serialization-bom = { module = "org.jetbrains.kotlinx:kotlinx-serialization-bom", version.ref = "kotlinx-serialization" }
@@ -83,7 +86,10 @@ gradlePlugin-android-dokkatoo = { module = "com.android.tools.build:gradle", ver
 gradlePlugin-androidApi-dokkatoo = { module = "com.android.tools.build:gradle-api", version.ref = "gradlePlugin-android-dokkatoo" }
 gradlePlugin-dokka = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "gradlePlugin-dokka" }
 gradlePlugin-shadow = { module = "com.github.johnrengelman:shadow", version.ref = "gradlePlugin-shadow" }
-gradlePlugin-gradlePublish= { module = "com.gradle.publish:plugin-publish-plugin", version.ref = "gradlePlugin-gradlePluginPublish" }
+gradlePlugin-gradlePublish = { module = "com.gradle.publish:plugin-publish-plugin", version.ref = "gradlePlugin-gradlePluginPublish" }
+
+gradlePlugin-gradle-customUserData = { module = "com.gradle:common-custom-user-data-gradle-plugin", version.ref = "gradlePlugin-gradle-customUserData" }
+gradlePlugin-gradle-enterprise = { module = "com.gradle:gradle-enterprise-gradle-plugin", version.ref = "gradlePlugin-gradle-enterprise" }
 
 #### Kotlin analysis ####
 kotlin-compiler = { module = "org.jetbrains.kotlin:kotlin-compiler", version.ref = "kotlin-compiler" }