Improve Build Caching of Maven plugin tasks (#3531)

- Update MvnExec task:
  - separate classes/resources inputs
  - filter and annotate classes input:
     1. only include `.class` files (the compileKotlin file includes caches)
     2. annotate with `@Classpath` so Gradle will be able to normalize the files

- Update `generatePom` task to manually register the version inputs, to ensure Gradle will re-run the task if they change.
- Update `helpMojoResources` to exclude `maven-plugin-help.properties`, because it contains a property with an absolute file path, meaning that Build Cache cannot be shared between CI and local machines.

build-logic/src/main/kotlin/dokkabuild/tasks/MvnExec.kt

@@ -4,10 +4,7 @@
 package dokkabuild.tasks
 
 import org.gradle.api.DefaultTask
-import org.gradle.api.file.ConfigurableFileCollection
-import org.gradle.api.file.DirectoryProperty
-import org.gradle.api.file.FileSystemOperations
-import org.gradle.api.file.RegularFileProperty
+import org.gradle.api.file.*
 import org.gradle.api.provider.ListProperty
 import org.gradle.api.provider.Property
 import org.gradle.api.tasks.*
@@ -35,16 +32,24 @@ constructor(
     /**
      * Work directory.
      *
-     * Be aware that any existing content will be replaced by [inputFiles].
+     * Be aware that any existing content will be replaced by [filteredClasses] and [resources].
      */
     @get:OutputDirectory
     abstract val workDirectory: DirectoryProperty
 
-    /** Input files - will be synced to [workDirectory]. */
+    /** Input classes - will be synced to [workDirectory]. */
+    @get:Internal
+    abstract val classes: ConfigurableFileCollection
+
+    @get:Classpath
+    protected val filteredClasses: FileCollection
+        get() = classes.asFileTree.matching { include("**/*.class") }
+
+    /** Input resource files - will be synced to [workDirectory]. */
     @get:InputFiles
     @get:PathSensitive(RELATIVE)
     @get:NormalizeLineEndings
-    abstract val inputFiles: ConfigurableFileCollection
+    abstract val resources: ConfigurableFileCollection
 
     @get:InputFile
     @get:PathSensitive(NONE)
@@ -66,7 +71,10 @@ constructor(
     @TaskAction
     fun exec() {
         fs.sync {
-            from(inputFiles)
+            from(filteredClasses) {
+                into("classes/java/main")
+            }
+            from(resources)
             into(workDirectory)
         }
 

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

@@ -33,18 +33,21 @@ val generatePom by tasks.registering(Sync::class) {
     val dokkaVersion = provider { project.version.toString() }
     inputs.property("dokkaVersion", dokkaVersion)
 
-    val pomTemplateFile = layout.projectDirectory.file("pom.template.xml")
+    val mavenVersion = mavenCliSetup.mavenVersion
+    inputs.property("mavenVersion", mavenVersion)
+
+    val mavenPluginToolsVersion = mavenCliSetup.mavenPluginToolsVersion
+    inputs.property("mavenPluginToolsVersion", mavenPluginToolsVersion)
 
-    val mavenVersion = mavenCliSetup.mavenVersion.orNull
-    val mavenPluginToolsVersion = mavenCliSetup.mavenPluginToolsVersion.orNull
+    val pomTemplateFile = layout.projectDirectory.file("pom.template.xml")
 
     from(pomTemplateFile) {
         rename { it.replace(".template.xml", ".xml") }
 
         expand(
-            "mavenVersion" to mavenVersion,
+            "mavenVersion" to mavenVersion.get(),
             "dokka_version" to dokkaVersion.get(),
-            "mavenPluginToolsVersion" to mavenPluginToolsVersion,
+            "mavenPluginToolsVersion" to mavenPluginToolsVersion.get(),
         )
     }
 
@@ -55,7 +58,7 @@ val generateHelpMojo by tasks.registering(MvnExec::class) {
     description = "Generate the Maven Plugin HelpMojo"
     group = mavenPluginTaskGroup
 
-    inputFiles.from(generatePom)
+    resources.from(generatePom)
     arguments.addAll(
         "org.apache.maven.plugins:maven-plugin-plugin:helpmojo"
     )
@@ -67,14 +70,16 @@ val helpMojoSources by tasks.registering(Sync::class) {
 
     from(generateHelpMojo) {
         eachFile {
-            // drop 2 leading directories
+            // Maven generates sources into `generated-sources/plugin/`,
+            // so drop 2 leading directories:
             relativePath = RelativePath(true, *relativePath.segments.drop(2).toTypedArray())
         }
     }
     includeEmptyDirs = false
 
     into(temporaryDir)
 
+    // this task prepares generated helpmojo _sources_, so only include source files
     include("**/*.java")
 }
 
@@ -86,32 +91,30 @@ val helpMojoResources by tasks.registering(Sync::class) {
 
     into(temporaryDir)
 
-    include("**/**")
-    exclude("**/*.java")
+    // this task prepares generated helpmojo _resources_, so...
+    include("**/**")       // include everything by default
+    exclude("**/*.java")   // don't include source files
+    // `maven-plugin-help.properties` contains an absolute path: destinationDirectory.
+    // Exclude it, so that Build Cache is relocatable.
+    exclude("**/maven-plugin-help.properties")
+
+    includeEmptyDirs = false
 }
 
 sourceSets.main {
-    // use the generated HelpMojo as compilation input, so Gradle will automatically generate the mojo
+    // use the generated HelpMojo tasks as compilation input: Gradle will automatically trigger the tasks when required
     java.srcDirs(helpMojoSources)
     resources.srcDirs(helpMojoResources)
 }
 
-val preparePluginDescriptorDir by tasks.registering(Sync::class) {
-    description = "Prepare files for generating the Maven Plugin descriptor"
-    group = mavenPluginTaskGroup
-
-    from(tasks.compileKotlin) { into("classes/java/main") }
-    from(tasks.compileJava) { into("classes/java/main") }
-    from(helpMojoResources)
-
-    into(temporaryDir)
-}
-
 val generatePluginDescriptor by tasks.registering(MvnExec::class) {
     description = "Generate the Maven Plugin descriptor"
     group = mavenPluginTaskGroup
 
-    inputFiles.from(preparePluginDescriptorDir)
+    classes.from(tasks.compileKotlin)
+    classes.from(tasks.compileJava)
+
+    resources.from(helpMojoResources)
 
     arguments.addAll(
         "org.apache.maven.plugins:maven-plugin-plugin:descriptor"