Document the plugin usage

[bric3]

Document the plugin usage

[jjohannes]

@bric3 It is working, but the dependency insight report does not show which jar is selected. As you see, here the "Java 8" compatible variant was picked.

com.google.guava:guava:28.1-android
   variant "jdk8Compile" [
      org.gradle.jvm.version         = 8 (compatible with: 11)
      org.gradle.status              = release (not requested)
      org.gradle.usage               = java-api
      org.gradle.libraryelements     = jar (compatible with: classes)
      org.gradle.category            = library

      Requested attributes not found in the selected variant:
         org.gradle.dependency.bundling = external
   ]
   Selection reasons:
      - By conflict resolution : between versions 28.1-android, 26.0-android and 28.0-android

In particular: org.gradle.jvm.version = 8 (compatible with: 11)

The module GAV itself is still com.google.guava:guava:28.1-android because we cannot change that anymore during variant selection. But it does not matter as with this plugin, 28.1-android and 28.1-jre are identical (except for the version String itself). Both 28.1-android and 28.1-jre provide both Guava variants. So first Gradle selects one of these Guava "versions" by version conflict resolution. For Gradle, these just look like different versions, because the variant is encoded in the version number - which is a "hack" Guava does as there is no variant concept in pom.

In a stage after that, Gradle chooses one of the variants. In your example it chooses the Java 8 variant as expected.

It would be nice, if Gradle has a reporting task built-in to show you the actual artifacts (jars) that are resolved. Unfortunately, it does not have it at the moment. You can write your own simple task for it, to verify that it is working as expected:

tasks.register("printJars") {
  doLast {
    configurations.compileClasspath.get().files.forEach { println(it.name) }
  }
}

Note: Version 0.1 of the plugin does not support the latest release (Guava 29.0). I plan to publish a new plugin version later today.

I will also attempt to add a readme to the repository explaining what I wrote here to avoid confusion for other users.

[jjohannes]

A new version of the plugin (0.2) has been released and the readme was updated.

[bric3]

@jjohannes Thank you for your insight. I might have built upon a wrong expectation from the plugin, that it will choose / substitute jre variant over the android one if the consumer is targetting a JDK. Thank you for rectifying this and explaing it to me !

Also I'm not sure about this though as both only ship one jar. What do you mean (ABI compatibility) ?

Both 28.1-android and 28.1-jre provide both Guava variants.

[jjohannes]

@bric3 I probably need to explain this a bit better. What the plugin does is effectively merging two versions of Guava (e.g. 28.1-android and 28.1-jre) into one. It assumes that these versions are always released together. 28.1-android and 28.1-jre are then identical versions from Gradle's point of view. And it does not matter which one you select.

Each version then has both jars in different variants. And Gradle selects one of them based on which JDK you are targeting.

If this information where published with Gradle Module Metadata, it would look like this:

  ...
  "variants": [
    {
      "name": "jdk8RuntimeElements",
      "attributes": {
        "org.gradle.category": "library",
        "org.gradle.jvm.version": 8,
        "org.gradle.libraryelements": "jar",
        "org.gradle.usage": "java-runtime"
      },
      "dependencies": [
        ...
      ],
      "files": [
        {
          "name": "guava-28.1-jre.jar",
          "url": "guava-28.1-jre.jar"
        }
      ]
    },
    {
      "name": "jdk6RuntimeElements",
      "attributes": {
        "org.gradle.category": "library",
        "org.gradle.jvm.version": 6,
        "org.gradle.libraryelements": "jar",
        "org.gradle.usage": "java-runtime"
      },
      "dependencies": [
        ...
      ],
      "files": [
        {
          "name": "guava-28.1-android.jar",
          "url": "../28.1-android/guava-28.1-android.jar"
        }
      ],
    }
  ]
}

(Guava will most likely publish this in the the next release - google/guava#3683 - and then this plugin would no longer be needed)