Skip to content

Commit

Permalink
Fix Maven plugin help task (#3036)
Browse files Browse the repository at this point in the history 
Fixes #3035
  • Loading branch information
@aSemy
aSemy committed Oct 11, 2023
1 parent 33210a4 commit 514cbb1
Show file tree
Hide file tree
Showing 6 changed files with 133 additions and 46 deletions.
3 changes: 0 additions & 3 deletions build-logic/src/main/kotlin/org/jetbrains/conventions/maven-cli-setup.gradle.kts
View file
Expand Up @@ -22,7 +22,6 @@ plugins {
abstract class MavenCliSetupExtension {
abstract val mavenVersion: Property<String>
abstract val mavenPluginToolsVersion: Property<String>
abstract val mavenBuildDir: DirectoryProperty

/** Directory that will contain the unpacked Apache Maven dependency */
abstract val mavenInstallDir: DirectoryProperty
Expand All @@ -43,7 +42,6 @@ val mavenCliSetupExtension =
mavenVersion.convention(libs.versions.apacheMaven.core)
mavenPluginToolsVersion.convention(libs.versions.apacheMaven.pluginTools)

mavenBuildDir.convention(layout.buildDirectory.dir("maven"))
mavenInstallDir.convention(layout.buildDirectory.dir("apache-maven"))

val isWindowsProvider =
Expand Down Expand Up @@ -81,7 +79,6 @@ val mavenBinary by configurations.registering {
}

tasks.clean {
delete(mavenCliSetupExtension.mavenBuildDir)
delete(mavenCliSetupExtension.mavenInstallDir)
}

Expand Down
50 changes: 47 additions & 3 deletions ...sts/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt
View file
Expand Up @@ -4,9 +4,10 @@

package org.jetbrains.dokka.it.maven

import org.intellij.lang.annotations.Language
import org.jetbrains.dokka.it.AbstractIntegrationTest
import org.jetbrains.dokka.it.awaitProcessResult
import org.jetbrains.dokka.it.ProcessResult
import org.jetbrains.dokka.it.awaitProcessResult
import java.io.File
import kotlin.test.*

Expand All @@ -26,11 +27,33 @@ class MavenIntegrationTest : AbstractIntegrationTest() {
writeText(readText().replace("\$dokka_version", currentDokkaVersion))
}
val customResourcesDir = File(templateProjectDir, "customResources")
if(customResourcesDir.exists() && customResourcesDir.isDirectory) {
if (customResourcesDir.exists() && customResourcesDir.isDirectory) {
customResourcesDir.copyRecursively(File(projectDir, "customResources"), overwrite = true)
}
}

@Test
fun `dokka help`() {
val result = ProcessBuilder().directory(projectDir)
.command(mavenBinaryFile.absolutePath, "dokka:help", "-U", "-e")
.start()
.awaitProcessResult()

// format the output to remove blank lines and make newlines system-independent
val output = result.output.lines().filter { it.isNotBlank() }.joinToString("\n")

assertContains(
output,
"""
|This plugin has 4 goals:
|dokka:dokka
|dokka:help
|dokka:javadoc
|dokka:javadocJar
""".trimMargin()
)
}

@Test
fun `dokka dokka`() {
val result = ProcessBuilder().directory(projectDir)
Expand Down Expand Up @@ -67,7 +90,12 @@ class MavenIntegrationTest : AbstractIntegrationTest() {
)
assertTrue(stylesDir.resolve("custom-style-to-add.css").isFile)
projectDir.allHtmlFiles().forEach { file ->
if(file.name != "navigation.html") assertTrue("custom-style-to-add.css" in file.readText(), "custom styles not added to html file ${file.name}")
if (file.name != "navigation.html") {
assertTrue(
"custom-style-to-add.css" in file.readText(),
"custom styles not added to html file ${file.name}"
)
}
}
assertTrue(stylesDir.resolve("custom-style-to-add.css").readText().contains("""/* custom stylesheet */"""))
assertTrue(imagesDir.resolve("custom-resource.svg").isFile)
Expand Down Expand Up @@ -172,4 +200,20 @@ class MavenIntegrationTest : AbstractIntegrationTest() {
)
)
}

companion object {
/*
* TODO replace with kotlin.test.assertContains after migrating to Kotlin language version 1.5+
*/
fun assertContains(
charSequence: CharSequence,
@Language("TEXT") other: CharSequence,
ignoreCase: Boolean = false
) {
asserter.assertTrue(
{ "Expected the char sequence to contain the substring.\nCharSequence <$charSequence>, substring <$other>, ignoreCase <$ignoreCase>." },
charSequence.contains(other, ignoreCase)
)
}
}
}
2 changes: 1 addition & 1 deletion integration-tests/src/main/kotlin/org/jetbrains/dokka/it/TestOutputCopier.kt
View file
Expand Up @@ -15,6 +15,6 @@ public interface TestOutputCopier {
System.getenv("DOKKA_TEST_OUTPUT_PATH")?.also { location ->
println("Copying to ${File(location).absolutePath}")
projectOutputLocation.copyRecursively(File(location))
} ?: println("No path via env. varbiable 'DOKKA_TEST_OUTPUT_PATH' provided, skipping copying")
} ?: println("No path via env. variable 'DOKKA_TEST_OUTPUT_PATH' provided, skipping copying")
}
}
5 changes: 5 additions & 0 deletions runners/maven-plugin/api/maven-plugin.api
View file
Expand Up @@ -94,6 +94,11 @@ public final class org/jetbrains/dokka/maven/ExternalDocumentationLinkBuilder {
public final fun setUrl (Ljava/net/URL;)V
}

public class org/jetbrains/dokka/maven/HelpMojo : org/apache/maven/plugin/AbstractMojo {
public fun <init> ()V
public fun execute ()V
}

public final class org/jetbrains/dokka/maven/MavenDokkaLogger : org/jetbrains/dokka/utilities/DokkaLogger {
public fun <init> (Lorg/apache/maven/plugin/logging/Log;)V
public fun debug (Ljava/lang/String;)V
Expand Down
93 changes: 54 additions & 39 deletions runners/maven-plugin/build.gradle.kts
View file
Expand Up @@ -2,7 +2,6 @@
* Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
*/

import org.gradle.kotlin.dsl.support.appendReproducibleNewLine
import org.jetbrains.registerDokkaArtifactPublication

plugins {
Expand Down Expand Up @@ -47,77 +46,93 @@ val generatePom by tasks.registering(Sync::class) {
into(temporaryDir)
}

val prepareMavenPluginBuildDir by tasks.registering(Sync::class) {
description = "Prepares all files for Maven Plugin task execution"
val prepareHelpMojoDir by tasks.registering(Sync::class) {
description = "Prepare files for generating the Maven Plugin HelpMojo"
group = mavenPluginTaskGroup

from(tasks.compileKotlin.flatMap { it.destinationDirectory }) { into("classes/java/main") }
from(tasks.compileJava.flatMap { it.destinationDirectory }) { into("classes/java/main") }

into(layout.buildDirectory.dir("maven-help-mojo"))
from(generatePom)

into(mavenCliSetup.mavenBuildDir)
}

val helpMojo by tasks.registering(Exec::class) {
description = "Generate the Maven Plugin HelpMojo"
group = mavenPluginTaskGroup

dependsOn(tasks.installMavenBinary, prepareMavenPluginBuildDir)
dependsOn(tasks.installMavenBinary, prepareHelpMojoDir)

workingDir(mavenCliSetup.mavenBuildDir)
workingDir(prepareHelpMojoDir.map { it.destinationDir })
executable(mavenCliSetup.mvn.get())
args("-e", "-B", "org.apache.maven.plugins:maven-plugin-plugin:helpmojo")

outputs.dir(mavenCliSetup.mavenBuildDir)

doLast("normalize maven-plugin-help.properties") {
// The maven-plugin-help.properties file contains a timestamp by default.
// It should be removed as it is not reproducible and impacts Gradle caching
val pluginHelpProperties = workingDir.resolve("maven-plugin-help.properties")
pluginHelpProperties.writeText(
buildString {
val lines = pluginHelpProperties.readText().lines().iterator()
// the first line is a descriptive comment
appendReproducibleNewLine(lines.next())
// the second line is the timestamp, which should be ignored
lines.next()
// the remaining lines are properties
lines.forEach { appendReproducibleNewLine(it) }
}
)
outputs.dir(workingDir)
}

val helpMojoSources by tasks.registering(Sync::class) {
description = "Sync the HelpMojo source files into a SourceSet SrcDir"
group = mavenPluginTaskGroup
from(helpMojo) {
eachFile {
// drop 2 leading directories
relativePath = RelativePath(true, *relativePath.segments.drop(2).toTypedArray())
}
}
includeEmptyDirs = false
into(temporaryDir)
include("**/*.java")
}

val helpMojoResources by tasks.registering(Sync::class) {
description = "Sync the HelpMojo resource files into a SourceSet SrcDir"
group = mavenPluginTaskGroup
from(helpMojo)
into(temporaryDir)
include("**/**")
exclude("**/*.java")
}

sourceSets.main {
// use the generated HelpMojo as compilation input, so Gradle will automatically generate the mojo
java.srcDirs(helpMojoSources)
resources.srcDirs(helpMojoResources)
}

val preparePluginDescriptorDir by tasks.registering(Sync::class) {
description = "Prepare files for generating the Maven Plugin descriptor"
group = mavenPluginTaskGroup

into(layout.buildDirectory.dir("maven-plugin-descriptor"))

from(tasks.compileKotlin) { into("classes/java/main") }
from(tasks.compileJava) { into("classes/java/main") }
from(helpMojoResources)
}

val pluginDescriptor by tasks.registering(Exec::class) {
description = "Generate the Maven Plugin descriptor"
group = mavenPluginTaskGroup

dependsOn(tasks.installMavenBinary, prepareMavenPluginBuildDir)
dependsOn(tasks.installMavenBinary, preparePluginDescriptorDir)

workingDir(mavenCliSetup.mavenBuildDir)
workingDir(preparePluginDescriptorDir.map { it.destinationDir })
executable(mavenCliSetup.mvn.get())
args(
"-e",
"-B",
"org.apache.maven.plugins:maven-plugin-plugin:descriptor"
)
args("-e", "-B", "org.apache.maven.plugins:maven-plugin-plugin:descriptor")

outputs.dir(layout.buildDirectory.dir("maven/classes/java/main/META-INF/maven"))
outputs.dir("$workingDir/classes/java/main/META-INF/maven")
}

tasks.jar {
dependsOn(pluginDescriptor, helpMojo)
metaInf {
from(mavenCliSetup.mavenBuildDir.map { it.dir("classes/java/main/META-INF") })
from(pluginDescriptor) {
into("maven")
}
}
manifest {
attributes("Class-Path" to configurations.runtimeClasspath.map { configuration ->
configuration.resolve().joinToString(" ") { it.name }
})
}
duplicatesStrategy = DuplicatesStrategy.WARN
}


registerDokkaArtifactPublication("dokkaMavenPlugin") {
artifactId = "dokka-maven-plugin"
}
26 changes: 26 additions & 0 deletions runners/maven-plugin/pom.template.xml
View file
Expand Up @@ -12,6 +12,7 @@
<packaging>maven-plugin</packaging>
<properties>
<maven.version>${mavenVersion}</maven.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<build>
<plugins>
Expand All @@ -21,10 +22,35 @@
<version>${mavenPluginToolsVersion}</version>
<configuration>
<helpPackageName>org.jetbrains.dokka.maven</helpPackageName>
<skipErrorNoDescriptorsFound>true</skipErrorNoDescriptorsFound>
</configuration>
<executions>
<execution>
<id>default-descriptor</id>
<goals>
<goal>descriptor</goal>
</goals>
<phase>process-classes</phase>
</execution>
<execution>
<id>help-descriptor</id>
<goals>
<goal>helpmojo</goal>
</goals>
<phase>process-classes</phase>
</execution>
</executions>
</plugin>
</plugins>
<directory>./</directory>
<outputDirectory>./classes/java/main</outputDirectory>
</build>
<dependencies>
<dependency>
<groupId>org.apache.maven.plugin-tools</groupId>
<artifactId>maven-plugin-annotations</artifactId>
<version>${mavenPluginToolsVersion}</version>
<scope>provided</scope>
</dependency>
</dependencies>
</project>

0 comments on commit 514cbb1

Please sign in to comment.