Configuring sourceLink per task is incompatible with configuration caching

[TheMrMilchmann]

The following snippet introduces references to objects that cause incompatibilities with Gradle's configuration caching:

tasks {
    dokkatooGenerateModuleHtml.configure {
        dokkaSourceSets.configureEach {
            sourceLink {
                // ...
            }
        }
    }
}

Writing the configuration cache fails (see also):

⌄ task:dokkatooGenerateModuleHtml of type dev.adamko.dokkatoo.tasks.DokkatooGenerateTask
  ⌄ field__dokkaSourceSets__ of dev.adamko.dokkatoo.tasks.DokkatooGenerateTask
    ⌄ bean of type org.gradle.api.internal.FactoryNamedDomainObjectContainer
      ⌄ fieldeventRegister of org.gradle.api.internal.FactoryNamedDomainObjectContainer
        ⌄ bean of type org.gradle.api.internal.collections.DefaultCollectionEventRegister
          ⌄ fieldaddActions of org.gradle.api.internal.collections.DefaultCollectionEventRegister
            ⌄ bean of type org.gradle.internal.ImmutableActionSet$SetWithFewActions
              ⌄ fieldactions of org.gradle.internal.ImmutableActionSet$SetWithFewActions
                ⌄ bean of type org.gradle.api.internal.DefaultMutationGuard$1
                  ⌄ fieldval$action of org.gradle.api.internal.DefaultMutationGuard$1
                    ⌄ bean of type org.gradle.api.internal.DefaultMutationGuard$1
                      ⌄ fieldval$action of org.gradle.api.internal.DefaultMutationGuard$1
                        ⌄ bean of type org.gradle.api.internal.DefaultCollectionCallbackActionDecorator$BuildOperationEmittingAction
                          ⌄ fielddelegate of org.gradle.api.internal.DefaultCollectionCallbackActionDecorator$BuildOperationEmittingAction
                            ⌄ bean of type org.gradle.configuration.internal.DefaultUserCodeApplicationContext$CurrentApplication$1
                              ⌄ fieldval$action of org.gradle.configuration.internal.DefaultUserCodeApplicationContext$CurrentApplication$1
                                ⌄ bean of type Build_gradle$4$5$1
                                  ⌄ fieldthis$0 of Build_gradle$4$5$1
                                    ■⚠️cannot serialize Gradle script object references as these are not supported with the configuration cache.[ ?](https://docs.gradle.org/8.1/userguide/configuration_cache.html#config_cache:requirements:disallowed_types)

This issue does not occur when configuring the sourceLink via the dokkatoo extension.

[aSemy]

Thanks for the issue, I've made a reproducer: #55

It seems to specifically be triggered by cross-project dependencies. I couldn't reproduce it in a single project.

I don't know what the cause might be. Unfortunately Gradle's Configuration Cache reports are essentially useless, they don't help diagnose anything.

[TheMrMilchmann]

Sorry, I forgot to talk about the project where I encountered this issue: https://github.com/GW2ToolBelt/api-generator/tree/0dae12da6a993333511227b59d7905ac515d6815. I didn't prepare a reproducer because the build is fairly straightforward. All relevant stuff is happening in build.gradle.kts.

There are no cross-project dependencies involved in my build. The relevant sections should be:

plugins {
    alias(libs.plugins.binary.compatibility.validator)
    alias(libs.plugins.dokkatoo.html) // 1.1.1
    alias(libs.plugins.dokkatoo.javadoc) // 1.1.1
    alias(libs.plugins.gradle.toolchain.switches)
    alias(libs.plugins.kotlin.jvm) // 1.8.20
    alias(libs.plugins.kotlin.plugin.serialization) // 1.8.20
    id("com.gw2tb.maven-publish-conventions")
}

(https://github.com/GW2ToolBelt/api-generator/blob/0dae12da6a993333511227b59d7905ac515d6815/build.gradle.kts#L28-L36)

tasks {
    dokkatooGenerateModuleHtml.configure {
        outputDirectory.set(layout.buildDirectory.dir("mkdocs/sources/api"))

        dokkaSourceSets.configureEach {
            reportUndocumented.set(true)
            skipEmptyPackages.set(true)
            jdkVersion.set(8)

            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(URL("https://github.com/GW2ToolBelt/api-generator/tree/v${version}/src/main/kotlin"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

(https://github.com/GW2ToolBelt/api-generator/blob/0dae12da6a993333511227b59d7905ac515d6815/build.gradle.kts#L89-L103)

You can reproduce the issue by checking out this specific commit locally and executing the dokkatooGenerateModuleHtml task.

[aSemy]

I think the issue is actually contained within the build script, and it isn't an issue with Dokkatoo.

This line uses the Project.file() function, and using Project is not allowed inside configureEach {} blocks (or something like that)

localDirectory.set(file("src/main/kotlin"))

If you refactor the script so it assigns the directory to a variable, it should work.

tasks {
    dokkatooGenerateModuleHtml.configure {

        // define a val to be compatible with CC
        val srcMainKotlinDir = layout.projectDirectory.dir("src/main/kotlin")

        outputDirectory.set(layout.buildDirectory.dir("mkdocs/sources/api"))

        dokkaSourceSets.configureEach {
            reportUndocumented.set(true)
            skipEmptyPackages.set(true)
            jdkVersion.set(8)

            sourceLink {
                localDirectory.set(srcMainKotlinDir)
                remoteUrl.set(URL("https://github.com/GW2ToolBelt/api-generator/tree/v${version}/src/main/kotlin"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

@TheMrMilchmann could you check, please?

[Vampire]

It is not only that, but also version.
Both file and version are delegated to the build script wich then delegates to the project.
This fixes it, so yes, not a dokkatoo issue:

diff --git a/build.gradle.kts b/build.gradle.kts
index 1acf54f..be5d7f8 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -89,13 +89,15 @@ tasks {
     dokkatooGenerateModuleHtml.configure {
         outputDirectory.set(layout.buildDirectory.dir("mkdocs/sources/api"))

+        val version = project.version
+        val srcMainKotlin = layout.projectDirectory.dir("src/main/kotlin")
         dokkaSourceSets.configureEach {
             reportUndocumented.set(true)
             skipEmptyPackages.set(true)
             jdkVersion.set(8)

             sourceLink {
-                localDirectory.set(file("src/main/kotlin"))
+                localDirectory.set(srcMainKotlin)
                 remoteUrl.set(URL("https://github.com/GW2ToolBelt/api-generator/tree/v${version}/src/main/kotlin"))
                 remoteLineSuffix.set("#L")
             }

[TheMrMilchmann]

Thanks, @aSemy, and thank you once again, @Vampire. This does the trick. I totally forgot about that and was further led in the wrong direction by the report. Unfortunately, this is way too easy to miss.

[aSemy]

Unfortunately, this is way too easy to miss.

Agreed! I wish that the HTML report provided more useful information. gradle/gradle#24030