DPG: Only apply 'Adapter' plugins once, and group PluginIds

adam-enko · adam-enko · commit 55d23db7b0d8 · 2025-11-19T12:09:58.000+01:00
The AndroidAdapter, JavaAdapter, and KotlinAdapters apply their configuration multiple times.

Currently, this is acceptable because a project cannot have multiple Android/Kotlin/Java plugins applied.
But the situation gets more complicated with AGP9 and kotlin-built-in.
The kotlin-built-in plugin uses an implementation of `KotlinBasePlugin`,
so the Android and Kotlin adapters could get applied multiple times, and some of their operations (registering DokkaSourceSets) aren't idempotent.

I also updated the JavaAdapter to use the same approach for consistency (it's not strictly necessary).

---

Also, group the plugin IDs into Sets, so they can be accessed at once without needing to remember which IDs should be accessed.
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/AndroidAdapter.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/AndroidAdapter.kt
@@ -16,6 +16,7 @@ import org.gradle.api.logging.Logging
 import org.gradle.api.model.ObjectFactory
 import org.gradle.api.provider.Provider
 import org.gradle.api.provider.ProviderFactory
+import org.gradle.kotlin.dsl.apply
 import org.gradle.kotlin.dsl.getByType
 import org.gradle.kotlin.dsl.withType
 import org.jetbrains.dokka.gradle.DokkaBasePlugin
@@ -41,16 +42,6 @@ abstract class AndroidAdapter @Inject constructor(
     override fun apply(project: Project) {
         logger.info("applied ${this::class} to ${project.path}")
 
-        project.plugins.withType<DokkaBasePlugin>().configureEach {
-            project.pluginManager.apply {
-                withPlugin(PluginId.AndroidBase) { configure(project) }
-                withPlugin(PluginId.AndroidApplication) { configure(project) }
-                withPlugin(PluginId.AndroidLibrary) { configure(project) }
-            }
-        }
-    }
-
-    protected fun configure(project: Project) {
         val dokkaExtension = project.extensions.getByType<DokkaExtension>()
 
         val androidExt = AndroidExtensionWrapper(project) ?: return
@@ -79,7 +70,21 @@ abstract class AndroidAdapter @Inject constructor(
     }
 
     @InternalDokkaGradlePluginApi
-    companion object
+    companion object {
+
+        /**
+         * Apply [AndroidAdapter] a single time to [project], regardless of how many AGP plugins are applied.
+         */
+        internal fun applyTo(project: Project) {
+            project.plugins.withType<DokkaBasePlugin>().all {
+                PluginId.androidPlugins.forEach { pluginId ->
+                    project.pluginManager.withPlugin(pluginId) {
+                        project.pluginManager.apply(AndroidAdapter::class)
+                    }
+                }
+            }
+        }
+    }
 }
 
 
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/JavaAdapter.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/JavaAdapter.kt
@@ -15,6 +15,7 @@ import org.gradle.api.tasks.SourceSet
 import org.gradle.api.tasks.SourceSet.MAIN_SOURCE_SET_NAME
 import org.gradle.api.tasks.SourceSet.TEST_SOURCE_SET_NAME
 import org.gradle.api.tasks.SourceSetContainer
+import org.gradle.kotlin.dsl.apply
 import org.gradle.kotlin.dsl.getByType
 import org.gradle.kotlin.dsl.withType
 import org.jetbrains.dokka.gradle.DokkaExtension
@@ -118,16 +119,11 @@ abstract class JavaAdapter @Inject constructor(
     ): Provider<Boolean> {
 
         val projectHasKotlinPlugin = providers.provider {
-            project.pluginManager.hasPlugin(PluginId.KotlinAndroid)
-                    || project.pluginManager.hasPlugin(PluginId.KotlinJs)
-                    || project.pluginManager.hasPlugin(PluginId.KotlinJvm)
-                    || project.pluginManager.hasPlugin(PluginId.KotlinMultiplatform)
+            PluginId.kgpPlugins.any { project.pluginManager.hasPlugin(it) }
         }
 
         val projectHasAndroidPlugin = providers.provider {
-            project.pluginManager.hasPlugin(PluginId.AndroidBase)
-                    || project.pluginManager.hasPlugin(PluginId.AndroidApplication)
-                    || project.pluginManager.hasPlugin(PluginId.AndroidLibrary)
+            PluginId.androidPlugins.any { project.pluginManager.hasPlugin(it) }
         }
 
         return projectHasKotlinPlugin or projectHasAndroidPlugin
@@ -147,5 +143,9 @@ abstract class JavaAdapter @Inject constructor(
         fun SourceSet.isPublished(): Boolean =
             name != TEST_SOURCE_SET_NAME
                     && name.startsWith(MAIN_SOURCE_SET_NAME)
+
+        internal fun applyTo(project: Project) {
+            project.pluginManager.apply(type = JavaAdapter::class)
+        }
     }
 }
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/KotlinAdapter.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/adapters/KotlinAdapter.kt
@@ -5,10 +5,7 @@ package org.jetbrains.dokka.gradle.adapters
 
 import com.android.build.api.variant.AndroidComponentsExtension
 import com.android.build.api.variant.Variant
-import org.gradle.api.Named
-import org.gradle.api.NamedDomainObjectContainer
-import org.gradle.api.Plugin
-import org.gradle.api.Project
+import org.gradle.api.*
 import org.gradle.api.file.ConfigurableFileCollection
 import org.gradle.api.file.FileCollection
 import org.gradle.api.logging.Logger
@@ -33,12 +30,9 @@ import org.jetbrains.kotlin.commonizer.stdlib
 import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
 import org.jetbrains.kotlin.gradle.dsl.KotlinProjectExtension
 import org.jetbrains.kotlin.gradle.dsl.KotlinSingleTargetExtension
-import org.jetbrains.kotlin.gradle.plugin.KotlinCompilation
+import org.jetbrains.kotlin.gradle.plugin.*
 import org.jetbrains.kotlin.gradle.plugin.KotlinCompilation.Companion.MAIN_COMPILATION_NAME
-import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType
 import org.jetbrains.kotlin.gradle.plugin.KotlinPlatformType.androidJvm
-import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
-import org.jetbrains.kotlin.gradle.plugin.getKotlinPluginVersion
 import org.jetbrains.kotlin.gradle.plugin.mpp.AbstractKotlinNativeCompilation
 import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinJvmAndroidCompilation
 import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinMetadataCompilation
@@ -62,17 +56,6 @@ abstract class KotlinAdapter @Inject constructor(
     override fun apply(project: Project) {
         logger.info("Applying $dkaName to ${project.path}")
 
-        project.plugins.withType<DokkaBasePlugin>().configureEach {
-            project.pluginManager.apply {
-                withPlugin(PluginId.KotlinAndroid) { exec(project) }
-                withPlugin(PluginId.KotlinJs) { exec(project) }
-                withPlugin(PluginId.KotlinJvm) { exec(project) }
-                withPlugin(PluginId.KotlinMultiplatform) { exec(project) }
-            }
-        }
-    }
-
-    private fun exec(project: Project) {
         val kotlinExtension = project.findKotlinExtension()
         if (kotlinExtension == null) {
             logger.info("Skipping applying $dkaName in ${project.path} - could not find KotlinProjectExtension")
@@ -210,6 +193,76 @@ abstract class KotlinAdapter @Inject constructor(
             val kgpVersion = getKotlinPluginVersion(logger)
             KotlinToolingVersion(kgpVersion)
         }
+
+        /**
+         * Applies [KotlinAdapter] to the current project when any plugin of type [KotlinBasePlugin]
+         * is applied.
+         *
+         * [KotlinBasePlugin] is the parent type for the Kotlin/JVM, Kotlin/Multiplatform, Kotlin/JS plugins,
+         * as well as AGP's kotlin-built-in plugin.
+         */
+        internal fun applyTo(project: Project) {
+            findKotlinBasePlugins(project)?.all {
+                project.pluginManager.apply(KotlinAdapter::class)
+            }
+        }
+
+        /**
+         * Tries fetching all plugins with type [KotlinBasePlugin],
+         * returning `null` if the class is not available in the current classloader.
+         *
+         * (The class might not be available if the current project is a Java or Android project,
+         * or the buildscripts have an inconsistent classpath https://github.com/gradle/gradle/issues/27218)
+         */
+        private fun findKotlinBasePlugins(project: Project): DomainObjectCollection<KotlinBasePlugin>? {
+            return try {
+                project.plugins.withType<KotlinBasePlugin>()
+            } catch (ex: Throwable) {
+                when (ex) {
+                    is ClassNotFoundException,
+                    is NoClassDefFoundError -> {
+                        logger.info("Dokka Gradle Plugin could not load KotlinBasePlugin in ${project.displayName} - ${ex::class.qualifiedName} ${ex.message}")
+                        logWarningIfKgpApplied(
+                            project,
+                            kotlinBasePluginNotFoundException = ex,
+                        )
+                        null
+                    }
+
+                    else -> throw ex
+                }
+            }
+        }
+
+        /**
+         * Check all plugins to see if they are a subtype of [KotlinBasePlugin].
+         * If any are, log a warning.
+         *
+         * ##### Motivation
+         *
+         * If the buildscript classpath is inconsistent, it might not be possible for DGP
+         * to react to KGP because the [KotlinBasePlugin] class can't be loaded.
+         * If so, DGP will be lenient and not cause errors,
+         * but it must display a prominent warning to help users find the problem.
+         *
+         * @param[kotlinBasePluginNotFoundException] The exception thrown when [KotlinBasePlugin] is not available.
+         */
+        private fun logWarningIfKgpApplied(
+            project: Project,
+            kotlinBasePluginNotFoundException: Throwable,
+        ) {
+            PluginId.kgpPlugins.forEach { pluginId ->
+                project.pluginManager.withPlugin(pluginId) {
+                    logger.warn(
+                        buildString {
+                            appendLine("Dokka Gradle Plugin could not load KotlinBasePlugin in ${project.displayName}, but plugin $id is applied.")
+                            appendLine("Check the buildscript classpath is consistent (all plugins are ")
+                        },
+                        kotlinBasePluginNotFoundException,
+                    )
+                }
+            }
+        }
     }
 }
 
@@ -298,10 +351,10 @@ private class KotlinCompilationDetailsBuilder(
     ): Provider<Set<AndroidVariantInfo>> {
         val androidVariants = objects.setProperty(AndroidVariantInfo::class)
 
-        project.pluginManager.apply {
-            withPlugin(PluginId.AndroidBase) { collectAndroidVariants(project, androidVariants) }
-            withPlugin(PluginId.AndroidApplication) { collectAndroidVariants(project, androidVariants) }
-            withPlugin(PluginId.AndroidLibrary) { collectAndroidVariants(project, androidVariants) }
+        PluginId.androidPlugins.forEach { pluginId ->
+            project.pluginManager.withPlugin(pluginId) {
+                collectAndroidVariants(project, androidVariants)
+            }
         }
 
         return androidVariants
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaFormatPlugin.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/formats/DokkaFormatPlugin.kt
@@ -65,9 +65,9 @@ abstract class DokkaFormatPlugin(
         target.pluginManager.apply(DokkaBasePlugin::class)
 
         // apply the plugin that will autoconfigure Dokka to use the sources of a Kotlin project
-        target.pluginManager.apply(type = KotlinAdapter::class)
-        target.pluginManager.apply(type = JavaAdapter::class)
-        target.pluginManager.apply(type = AndroidAdapter::class)
+        KotlinAdapter.applyTo(target)
+        AndroidAdapter.applyTo(target)
+        JavaAdapter.applyTo(target)
 
         target.plugins.withType<DokkaBasePlugin>().configureEach {
             val dokkaExtension = target.extensions.getByType(DokkaExtension::class)
diff --git a/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/PluginId.kt b/dokka-runners/dokka-gradle-plugin/src/main/kotlin/internal/PluginId.kt
@@ -9,12 +9,23 @@ package org.jetbrains.dokka.gradle.internal
 @Suppress("ConstPropertyName")
 internal object PluginId {
 
-    const val KotlinAndroid = "org.jetbrains.kotlin.android"
-    const val KotlinJs = "org.jetbrains.kotlin.js"
-    const val KotlinJvm = "org.jetbrains.kotlin.jvm"
-    const val KotlinMultiplatform = "org.jetbrains.kotlin.multiplatform"
+    private const val KotlinAndroid = "org.jetbrains.kotlin.android"
+    private const val KotlinJs = "org.jetbrains.kotlin.js"
+    private const val KotlinJvm = "org.jetbrains.kotlin.jvm"
+    private const val KotlinMultiplatform = "org.jetbrains.kotlin.multiplatform"
+    val kgpPlugins: Set<String> = setOf(
+        KotlinAndroid,
+        KotlinJs,
+        KotlinJvm,
+        KotlinMultiplatform,
+    )
 
-    const val AndroidBase = "com.android.base"
-    const val AndroidApplication = "com.android.application"
-    const val AndroidLibrary = "com.android.library"
+    private const val AndroidBase = "com.android.base"
+    private const val AndroidApplication = "com.android.application"
+    private const val AndroidLibrary = "com.android.library"
+    val androidPlugins: Set<String> = setOf(
+        AndroidBase,
+        AndroidApplication,
+        AndroidLibrary,
+    )
 }
diff --git a/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt b/dokka-runners/dokka-gradle-plugin/src/testFunctional/kotlin/MultiModuleFunctionalTest.kt
@@ -518,19 +518,33 @@ class MultiModuleFunctionalTest : FunSpec({
             }
         }
 
-        test("expect warning regarding KotlinProjectExtension") {
+        test("expect KotlinAdapter not applied to root project") {
             project.runner
                 .addArguments(
                     "clean",
                     "--stacktrace",
+                    "--info",
                 )
-                .forwardOutput()
                 .build {
-                    // the root project doesn't have the KGP applied, so KotlinProjectExtension shouldn't be applied
-                    output shouldNotContain "Dokka Gradle plugin failed to get extension kotlin org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension in :\n"
+                    // the root project doesn't have KGP applied, so KotlinAdapter shouldn't be applied
+                    output shouldContain "Dokka Gradle Plugin could not load KotlinBasePlugin in root project 'kpe-warning'"
+                    output shouldNotContain "Applying KotlinAdapter to :\n"
+                }
+        }
 
-                    output shouldContain "Dokka Gradle plugin failed to get extension kotlin org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension in :subproject-hello\n"
-                    output shouldContain "Dokka Gradle plugin failed to get extension kotlin org.jetbrains.kotlin.gradle.dsl.KotlinJvmProjectExtension in :subproject-goodbye\n"
+        test("expect KotlinAdapter applied to subprojects, with KotlinProjectExtension warnings") {
+            project.runner
+                .addArguments(
+                    "clean",
+                    "--stacktrace",
+                    "--warn",
+                )
+                .build {
+                    // the subprojects should have KotlinAdapter applied, but the extension should be unavailable
+                    // because the buildscript classpath is inconsistent.
+                    // (DGP is applied to the root project, but KGP is not.)
+                    output shouldContain "Dokka Gradle Plugin could not load KotlinBasePlugin in project ':subproject-hello', but plugin org.jetbrains.kotlin.jvm is applied"
+                    output shouldContain "Dokka Gradle Plugin could not load KotlinBasePlugin in project ':subproject-goodbye', but plugin org.jetbrains.kotlin.jvm is applied"
                 }
         }
     }
