Consider using different Gradle attributes for `dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable`

[martinbonnin]

After upgrating to 2.1.0, we started having KSP errors because the KSP classpath would select the dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable variant of some projects instead of the jvmRuntimeElements ones. They are indeed quite similar:

--------------------------------------------------
Variant dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable
--------------------------------------------------
Shared Dokka Plugins for consumers that will assemble a html Publication using the Dokka Module that this project produces

Capabilities
    - com.apollographql.apollo3:apollo-ast:4.0.0-beta.5-SNAPSHOT (default capability)
Attributes
    - dev.adamko.dokkatoo.classpath  = dokka-publication-plugins
    - dev.adamko.dokkatoo.format     = html
    - org.gradle.category            = library
    - org.gradle.dependency.bundling = external
    - org.gradle.jvm.environment     = standard-jvm
    - org.gradle.libraryelements     = jar
    - org.gradle.usage               = java-runtime

vs

--------------------------------------------------
Variant jvmRuntimeElements
--------------------------------------------------
Elements of runtime for main.

Capabilities
    - com.apollographql.apollo3:apollo-ast:4.0.0-beta.5-SNAPSHOT (default capability)
Attributes
    - org.gradle.category                = library
    - org.gradle.jvm.environment         = standard-jvm
    - org.gradle.libraryelements         = jar
    - org.gradle.usage                   = java-runtime
    - org.jetbrains.kotlin.platform.type = jvm
Artifacts
    - build/libs/apollo-ast-jvm-4.0.0-beta.5-SNAPSHOT.jar (artifactType = jar)

I was able to workaround by forcing "unselection" of the dokkatoo variant:

  configurations.configureEach {
    if (name.lowercase().contains("dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable".lowercase())) {
      attributes {
        attribute(Usage.USAGE_ATTRIBUTE, objects.named(Usage::class.java, "poison"))
      }
    }
  }

TBH I'm not 100% what the root cause is but would it be possible to use more specific attributes for dokkatooHtmlPublicationPluginClasspathApiOnlyConsumable? Maybe org.gradle.usage = dokkatoo-plugin?

[aSemy]

Thanks for the report!

The configurations have different attributes so it's a mystery why Gradle is confusing them.

I've tried various combinations of setting org.gradle.usage but nothing seems to work. It needs to be set to 'java-runtime', otherwise Gradle won't fetch the dependency from Maven Central.

Possibly it's an issue with KSP, which doesn't seem to add any attributes to its Configurations.

It looks like this is another bug/flaw/undocumented feature in Gradle so I've raised an issue https://github.com/gradle/gradle/issues/28053. I'm not sure how best to workaround it.

[martinbonnin]

Smaller reproducer with included builds instead of KSP here: https://github.com/martinbonnin/reproducer-attributes

tldr; not really sure what's happening down there but given all the existing ecosystem around this, I'd feel more comfortable if the dokkattoo artifacts were using a dedicated org.gradle.usage attribute. Maybe there need to be an "intermediate" configuration? One that resolves from Maven Central using java-runtime but then exposes something else in outgoingVariants?

[aSemy]

This issue seems relevant https://github.com/gradle/gradle/issues/26463

[aSemy]

#173 seems to have helped in some cases, but not all

https://github.com/apollographql/apollo-kotlin/commit/a58454c7d3f3bfcd7ea2fd64938b10f69571d402

[martinbonnin]

Right. It's working when everything is in the same build but failing to compile build scripts in composite builds. From that commit ./gradlew -p tests build fails IIRC

[aSemy]

hey @martinbonnin, when you try K2 could you also try and remove the 'poison' workaround? I'm curious whether it would help. See https://github.com/adamko-dev/dokkatoo/issues/170#issuecomment-2094210736

[martinbonnin]

Not working for us sadly (~commit~ good commit (see below)):

$ ./gradlew -p tests build

> Configure project :compiler-plugins-app
w: file:///Users/mbonnin/git/apollo-kotlin/tests/compiler-plugins/app/build.gradle.kts:1:1: @OptIn without any arguments has no effect
e: file:///Users/mbonnin/git/apollo-kotlin/tests/compiler-plugins/app/build.gradle.kts:1:13: Unresolved reference: ApolloExperimental
e: file:///Users/mbonnin/git/apollo-kotlin/tests/compiler-plugins/app/build.gradle.kts:1:13: An annotation argument must be a compile-time constant
e: file:///Users/mbonnin/git/apollo-kotlin/tests/compiler-plugins/app/build.gradle.kts:3:34: Unresolved reference: annotations

This somewhat fails when resolving included build. Note that this commit is using KGP RC2 but languageVersion 1.9 because we're stuck on other issues to enable languageVersion 2.0 (but I'd say the important thing is the KGP version here?)

[aSemy]

Thanks for trying! Did you also check with the latest Dokkatoo version? The commit you linked shows v2.2.0, but the latest is v2.3.1. This contains a fix relevant for composite builds - https://github.com/gradle/gradle/issues/28695

[martinbonnin]

Wooops, apologies I didn't realize there was an old branch named update-dokkatoo and my push didn't go through.

This is the good commit I tried yesterday. It still fails with 2.3.1 sadly.