build config: Use buildSrc convention plugins to configure the Dokka subprojects

.github/workflows/gh-actions-artifacts-snapshots.yml

@@ -18,7 +18,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 12
+          java-version: 11
           cache: 'maven'
       - name: Document coroutines
         uses: gradle/gradle-build-action@v2
@@ -44,7 +44,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 12
+          java-version: 11
           cache: 'maven'
       - name: Document serialization
         uses: gradle/gradle-build-action@v2
@@ -70,7 +70,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 12
+          java-version: 11
           cache: 'maven'
       - name: Document biojava-core
         uses: gradle/gradle-build-action@v2

.github/workflows/s3-snapshots.yml

@@ -18,7 +18,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 12
+          java-version: 11
           cache: 'maven'
       - name: Document coroutines
         uses: gradle/gradle-build-action@v2
@@ -48,7 +48,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 12
+          java-version: 11
           cache: 'maven'
       - name: Document serialization
         uses: gradle/gradle-build-action@v2
@@ -78,7 +78,7 @@ jobs:
       - uses: actions/setup-java@v3
         with:
           distribution: 'zulu'
-          java-version: 12
+          java-version: 11
           cache: 'maven'
       - name: Document biojava-core
         uses: gradle/gradle-build-action@v2

build.gradle.kts

@@ -1,76 +1,21 @@
-import org.jetbrains.*
-import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+import org.jetbrains.ValidatePublications
+import org.jetbrains.publicationChannels
 
 plugins {
-    kotlin("jvm") apply false
-    id("java")
-    id("org.jetbrains.dokka") version "1.8.10"
+    org.jetbrains.conventions.base
+    id("org.jetbrains.dokka")
     id("io.github.gradle-nexus.publish-plugin")
-}
-
-val dokka_version: String by project
-
-allprojects {
-    configureDokkaVersion()
 
-    group = "org.jetbrains.dokka"
-    version = dokka_version
-
-
-    val language_version: String by project
-    tasks.withType(KotlinCompile::class).all {
-        kotlinOptions {
-            freeCompilerArgs = freeCompilerArgs + listOf(
-                "-opt-in=kotlin.RequiresOptIn",
-                "-Xjsr305=strict",
-                "-Xskip-metadata-version-check",
-                // need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4)
-                "-Xsuppress-version-warnings"
-            )
-            allWarningsAsErrors = true
-            languageVersion = language_version
-            apiVersion = language_version
-            jvmTarget = "1.8"
-        }
-    }
-
-    repositories {
-        mavenCentral()
-    }
+    id("org.jetbrains.kotlinx.binary-compatibility-validator")
 }
 
-subprojects {
-    apply {
-        plugin("org.jetbrains.kotlin.jvm")
-        plugin("java")
-        plugin("signing")
-        plugin("org.jetbrains.dokka")
-    }
-
-    // Gradle metadata
-    java {
-        @Suppress("UnstableApiUsage")
-        withSourcesJar()
-        targetCompatibility = JavaVersion.VERSION_1_8
-    }
-
-    tasks {
-        val dokkaOutputDir = "$buildDir/dokka"
+val dokka_version: String by project
 
-        dokkaHtml {
-            onlyIf { !isLocalPublication }
-            outputDirectory.set(file(dokkaOutputDir))
-        }
+group = "org.jetbrains.dokka"
+version = dokka_version
 
-        register<Jar>("javadocJar") {
-            archiveClassifier.set("javadoc")
-            dependsOn(dokkaHtml)
-            from(dokkaOutputDir)
-        }
-    }
-}
 
-println("Publication version: $dokka_version")
+logger.lifecycle("Publication version: $dokka_version")
 tasks.register<ValidatePublications>("validatePublications")
 
 nexusPublishing {
@@ -82,8 +27,28 @@ nexusPublishing {
     }
 }
 
-tasks.maybeCreate("dokkaPublish").run {
+val dokkaPublish by tasks.registering {
     if (publicationChannels.any { it.isMavenRepository() }) {
         finalizedBy(tasks.named("closeAndReleaseSonatypeStagingRepository"))
     }
 }
+
+apiValidation {
+    // note that subprojects are ignored by their name, not their path https://github.com/Kotlin/binary-compatibility-validator/issues/16
+    ignoredProjects += setOf(
+        // NAME                    PATH
+        "search-component",    // :plugins:search-component
+        "frontend",            // :plugins:base:frontend
+
+        "kotlin-analysis",     // :kotlin-analysis
+        "compiler-dependency", // :kotlin-analysis:compiler-dependency
+        "intellij-dependency", // :kotlin-analysis:intellij-dependency
+
+        "integration-tests",   // :integration-tests
+        "gradle",              // :integration-tests:gradle
+        "cli",                 // :integration-tests:cli
+        "maven",               // integration-tests:maven
+
+        "test-utils",          // :test-utils
+    )
+}

buildSrc/build.gradle.kts

@@ -1,13 +1,32 @@
+import java.util.*
+
 plugins {
     `kotlin-dsl`
 }
 
-repositories {
-    gradlePluginPortal()
+kotlin {
+    jvmToolchain {
+        languageVersion.set(JavaLanguageVersion.of(8))
+    }
+}
+
+// TODO define versions in Gradle Version Catalog https://github.com/Kotlin/dokka/pull/2884
+val properties = file("../gradle.properties").inputStream().use {
+    Properties().apply { load(it) }
 }
 
+val kotlinVersion = properties["kotlin_version"]
+
 dependencies {
-    implementation("com.github.jengelman.gradle.plugins:shadow:2.0.4")
-    implementation("org.jetbrains.kotlinx:binary-compatibility-validator:0.10.1")
+    // Import Gradle Plugins that will be used in the buildSrc pre-compiled script plugins, and any `build.gradle.kts`
+    // files in the project.
+    // Use their Maven coordinates (plus versions), not Gradle plugin IDs!
+    // This should be the only place that Gradle plugin versions are defined, so they are aligned across all build scripts
+
+    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlinVersion")
+    implementation("gradle.plugin.com.github.johnrengelman:shadow:7.1.2")
+    implementation("org.jetbrains.kotlinx:binary-compatibility-validator:0.12.1")
     implementation("io.github.gradle-nexus:publish-plugin:1.1.0")
+    implementation("org.jetbrains.dokka:dokka-gradle-plugin:1.8.10")
+    implementation("com.gradle.publish:plugin-publish-plugin:0.20.0")
 }

buildSrc/settings.gradle.kts

@@ -0,0 +1,17 @@
+rootProject.name = "buildSrc"
+
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+}
+
+@Suppress("UnstableApiUsage")
+dependencyResolutionManagement {
+    repositories {
+        mavenCentral()
+        google()
+        gradlePluginPortal()
+    }
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/base-java.gradle.kts

@@ -0,0 +1,22 @@
+package org.jetbrains.conventions
+
+/**
+ * Base configuration for Java projects.
+ *
+ * This convention plugin contains shared Java config for both the [KotlinJvmPlugin] convention plugin and
+ * the Gradle Plugin subproject (which cannot have the `kotlin("jvm")` plugin applied).
+ */
+
+plugins {
+    `java`
+}
+
+java {
+    toolchain {
+        languageVersion.set(JavaLanguageVersion.of(8))
+    }
+}
+
+java {
+    withSourcesJar()
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/base.gradle.kts

@@ -0,0 +1,12 @@
+package org.jetbrains.conventions
+
+plugins {
+    base
+}
+
+// common Gradle configuration that should be applied to all projects
+
+if (project != rootProject) {
+    project.group = rootProject.group
+    project.version = rootProject.version
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka-integration-test.gradle.kts

@@ -0,0 +1,75 @@
+package org.jetbrains.conventions
+
+import org.gradle.api.tasks.testing.logging.TestExceptionFormat
+import org.gradle.api.tasks.testing.logging.TestLogEvent
+
+plugins {
+    id("org.jetbrains.conventions.kotlin-jvm")
+}
+
+val integrationTestSourceSet = sourceSets.create("integrationTest") {
+    compileClasspath += sourceSets.main.get().output
+    runtimeClasspath += sourceSets.main.get().output
+}
+
+val integrationTestImplementation by configurations.getting {
+    extendsFrom(configurations.implementation.get())
+}
+
+val integrationTestRuntimeOnly by configurations.getting {
+    extendsFrom(configurations.runtimeOnly.get())
+}
+
+/**
+ * Dokka's integration test task is not cacheable because the HTML outputs
+ * it produces when running the tests are used for showcasing resulting documentation,
+ * which does not work well with caching.
+ *
+ * At the moment there are two problems that do not allow to make it cacheable:
+ *
+ * 1. The task's inputs are such that changes in Dokka's code do not invalidate the cache,
+ *    because it is run with the same version of Dokka (`"DOKKA_VERSION"`) on the same
+ *    test project inputs.
+ * 2. The tests generate HTML output which is then used to showcase documentation.
+ *    The outputs are usually copied to a location from which it will be served.
+ *    However, if the test is cacheable, it produces no outputs, so no documentation
+ *    to showcase. It needs to be broken into two separate tasks: one cacheable for running
+ *    the tests and producing HTML output, and another non-cacheable for copying the output.
+ *
+ * @see [org.jetbrains.dokka.it.TestOutputCopier] for more details on showcasing documentation
+ */
+@DisableCachingByDefault(because = "Contains incorrect inputs/outputs configuration, see the KDoc for details")
+abstract class NonCacheableIntegrationTest : Test()
+
+val integrationTest by tasks.registering(NonCacheableIntegrationTest::class) {
+    maxHeapSize = "2G"
+    description = "Runs integration tests."
+    group = "verification"
+    useJUnit()
+
+    testClassesDirs = integrationTestSourceSet.output.classesDirs
+    classpath = integrationTestSourceSet.runtimeClasspath
+
+    setForkEvery(1)
+    project.properties["dokka_integration_test_parallelism"]?.toString()?.toIntOrNull()?.let { parallelism ->
+        maxParallelForks = parallelism
+    }
+    environment(
+        "isExhaustive",
+        project.properties["dokka_integration_test_is_exhaustive"]?.toString()?.toBoolean()
+            ?: System.getenv("DOKKA_INTEGRATION_TEST_IS_EXHAUSTIVE")?.toBoolean()
+            ?: false.toString()
+    )
+
+    testLogging {
+        exceptionFormat = TestExceptionFormat.FULL
+        events(TestLogEvent.SKIPPED, TestLogEvent.FAILED)
+        showExceptions = true
+        showCauses = true
+        showStackTraces = true
+    }
+}
+
+tasks.check {
+    dependsOn(integrationTest)
+}

buildSrc/src/main/kotlin/org/jetbrains/conventions/dokka.gradle.kts

@@ -0,0 +1,13 @@
+package org.jetbrains.conventions
+
+import org.gradle.kotlin.dsl.invoke
+import org.jetbrains.isLocalPublication
+
+plugins {
+    id("org.jetbrains.dokka")
+}
+
+tasks.dokkaHtml {
+    onlyIf { !isLocalPublication }
+    outputDirectory.set(layout.buildDirectory.dir("dokka").map { it.asFile })
+}