Use fixated Kotlin compiler 2.0.20 for compiling Dokka

Author: whyoleg

build-logic/src/main/kotlin/dokkabuild.gradle-plugin.gradle.kts

@@ -2,22 +2,16 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
+import dokkabuild.utils.configureGradleKotlinCompatibility
 import dokkabuild.utils.excludeGradleEmbeddedDependencies
-import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
 
 plugins {
     id("org.gradle.kotlin.kotlin-dsl")
     id("dokkabuild.java")
     id("dokkabuild.publish-gradle-plugin")
 }
 
-kotlin {
-    compilerOptions {
-        // Must use Kotlin 1.4 to support Gradle 7
-        languageVersion = @Suppress("DEPRECATION") KotlinVersion.KOTLIN_1_4
-        apiVersion = @Suppress("DEPRECATION") KotlinVersion.KOTLIN_1_4
-    }
-}
+configureGradleKotlinCompatibility()
 
 tasks.compileKotlin {
     compilerOptions {

build-logic/src/main/kotlin/dokkabuild.kotlin-jvm.gradle.kts

@@ -2,19 +2,22 @@
  * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
  */
 
+import dokkabuild.utils.configureGradleKotlinCompatibility
+
 plugins {
     id("dokkabuild.java")
     kotlin("jvm")
 }
 
 val rootProjectsWithoutDependencyOnDokkaCore = listOf("dokka-integration-tests")
 
+configureGradleKotlinCompatibility()
+
 kotlin {
     explicitApi()
+
     compilerOptions {
         allWarningsAsErrors = true
-        languageVersion = dokkaBuild.kotlinLanguageLevel
-        apiVersion = dokkaBuild.kotlinLanguageLevel
 
         // These projects know nothing about the `@InternalDokkaApi` annotation, so the Kotlin compiler
         // will complain about an unresolved opt-in requirement marker and fail the build if it's not excluded.
@@ -24,13 +27,5 @@ kotlin {
                 "org.jetbrains.dokka.InternalDokkaApi"
             )
         }
-
-        freeCompilerArgs.addAll(
-            // need 1.4 support, otherwise there might be problems
-            // with Gradle 6.x (it's bundling Kotlin 1.4)
-            "-Xsuppress-version-warnings",
-            "-Xjsr305=strict",
-            "-Xskip-metadata-version-check",
-        )
     }
 }

build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt

@@ -59,13 +59,10 @@ abstract class DokkaBuildProperties @Inject constructor(
         dokkaProperty("javaToolchain.testLauncher", JavaLanguageVersion::of)
             .orElse(mainJavaVersion)
 
-    /**
-     * The Kotlin language level that Dokka artifacts are compiled to support.
-     *
-     * Updating the language level is a breaking change.
-     */
-    val kotlinLanguageLevel: Provider<KotlinVersion> =
-        dokkaProperty("kotlinLanguageLevel", KotlinVersion::fromVersion)
+    /** Indicates whether Kotlin compatibility with older Gradle versions should be enforced */
+    val enforceGradleKotlinCompatibility: Provider<Boolean> =
+        dokkaProperty("enforceGradleKotlinCompatibility", String::toBoolean)
+            .orElse(true)
 
     /** Allows skipping running of integration tests */
     val integrationTestSkip: Provider<Boolean> =

build-logic/src/main/kotlin/dokkabuild/utils/gradleKotlinCompatibility.kt

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2014-2025 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package dokkabuild.utils
+
+import org.gradle.api.Project
+import org.gradle.kotlin.dsl.dokkaBuild
+import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
+import org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension
+import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
+
+// We must use Kotlin language/api version 1.4 (DEPRECATED) to support Gradle 7,
+// and to do that we need to use old Kotlin version, which has support for such an old Kotlin version (e.g., 2.0.20)
+fun Project.configureGradleKotlinCompatibility() {
+    if (!dokkaBuild.enforceGradleKotlinCompatibility.get()) return
+
+    extensions.configure<KotlinJvmProjectExtension>("kotlin") {
+        @OptIn(ExperimentalKotlinGradlePluginApi::class)
+        compilerVersion.set("2.0.20")
+        coreLibrariesVersion = "2.0.20"
+        compilerOptions {
+            languageVersion.set(KotlinVersion.fromVersion("1.4"))
+            apiVersion.set(KotlinVersion.fromVersion("1.4"))
+            freeCompilerArgs.add("-Xsuppress-version-warnings")
+        }
+    }
+}

dokka-integration-tests/gradle.properties

@@ -10,6 +10,7 @@ version=2.0.20-SNAPSHOT
 org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8
 org.jetbrains.dokka.integration_test.parallelism=2
+org.jetbrains.dokka.enforceGradleKotlinCompatibility=false
 
 # !!! ATTENTION: do not commit this !!!
 # Uncomment next line to skip running Dokka integration tests

dokka-integration-tests/gradle/build.gradle.kts

@@ -22,7 +22,7 @@ dependencies {
 
     api(libs.jsoup)
 
-    api(libs.kotlin.test)
+    api(kotlin("test-junit5"))
     api(libs.junit.jupiterApi)
     api(libs.junit.jupiterParams)
     api(libs.kotest.assertionsCore)

dokka-integration-tests/maven/build.gradle.kts

@@ -19,7 +19,7 @@ plugins {
 dependencies {
     api(projects.utilities)
 
-    api(libs.kotlin.test)
+    api(kotlin("test-junit5"))
     api(libs.junit.jupiterApi)
 
     val dokkaVersion = project.version.toString()

dokka-runners/dokka-gradle-plugin/build.gradle.kts

@@ -153,7 +153,7 @@ testing.suites {
             implementation(libs.kotlinxSerialization.json)
 
             //region classic-plugin dependencies - delete these when src/classicMain is removed
-            implementation(libs.kotlin.test)
+            implementation(project.dependencies.kotlin("test").toString())
             implementation(libs.gradlePlugin.kotlin)
             implementation(libs.gradlePlugin.kotlin.klibCommonizerApi)
             implementation(libs.gradlePlugin.android)

dokka-runners/dokka-gradle-plugin/gradle.properties

@@ -8,7 +8,7 @@ version=2.0.20-SNAPSHOT
 
 org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8
-org.jetbrains.dokka.kotlinLanguageLevel=1.4
+kotlin.compiler.runViaBuildToolsApi=true
 
 # Gradle settings
 org.gradle.jvmargs=-Dfile.encoding=UTF-8

dokka-runners/runner-cli/gradle.properties

@@ -8,4 +8,4 @@ version=2.0.20-SNAPSHOT
 
 org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8
-org.jetbrains.dokka.kotlinLanguageLevel=1.4
+kotlin.compiler.runViaBuildToolsApi=true

dokka-runners/runner-maven-plugin/gradle.properties

@@ -6,4 +6,4 @@ version=2.0.20-SNAPSHOT
 
 org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8
-org.jetbrains.dokka.kotlinLanguageLevel=1.4
+kotlin.compiler.runViaBuildToolsApi=true

gradle.properties

@@ -8,7 +8,7 @@ version=2.0.20-SNAPSHOT
 
 org.jetbrains.dokka.javaToolchain.mainCompiler=8
 org.jetbrains.dokka.javaToolchain.testLauncher=8
-org.jetbrains.dokka.kotlinLanguageLevel=1.4
+kotlin.compiler.runViaBuildToolsApi=true
 
 # Code style
 kotlin.code.style=official

gradle/libs.versions.toml

@@ -1,5 +1,8 @@
 [versions]
 
+# We use a different compiler version to compile modules and Gradle Plugin
+# to be able to use Kotlin Language/API version 1.4 to be compatible with Gradle 7.
+# The logic leaves in build-logic/src/main/kotlin/dokkabuild/utils/gradleKotlinCompatibility.kt
 gradlePlugin-kotlin = "2.0.20"
 # See: https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin
 gradlePlugin-android = "7.1.3"
@@ -142,8 +145,6 @@ kotlinx-cli = { module = "org.jetbrains.kotlinx:kotlinx-cli-jvm", version.ref =
 #### Test dependencies  ####
 eclipse-jgit = { module = "org.eclipse.jgit:org.eclipse.jgit", version.ref = "eclipse-jgit" }
 
-kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test-junit5", version.ref = "gradlePlugin-kotlin" }
-
 junit-bom = { module = "org.junit:junit-bom", version.ref = "junit" }
 junit-jupiterApi = { module = "org.junit.jupiter:junit-jupiter-api", version.ref = "junit" }
 junit-jupiterParams = { module = "org.junit.jupiter:junit-jupiter-params", version.ref = "junit" }