KT-64377 Maven dev publish

build-logic/src/main/kotlin/dokkabuild.base.gradle.kts

@@ -21,9 +21,3 @@ tasks.withType<AbstractArchiveTask>().configureEach {
     isPreserveFileTimestamps = false
     isReproducibleFileOrder = true
 }
-
-val integrationTestPreparation by tasks.registering {
-    description =
-        "lifecycle task for preparing the project for integration tests (for example, publishing to the test Maven repo)"
-    group = VERIFICATION_GROUP
-}

build-logic/src/main/kotlin/dokkabuild.dev-maven-publish.gradle.kts

@@ -0,0 +1,122 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+import dokkabuild.DevMavenPublishExtension
+import dokkabuild.DevMavenPublishExtension.Companion.DEV_MAVEN_PUBLISH_EXTENSION_NAME
+import dokkabuild.internal.consumable
+import dokkabuild.internal.declarable
+import dokkabuild.internal.resolvable
+import org.gradle.kotlin.dsl.support.uppercaseFirstChar
+
+/**
+ * Utility for publishing a project to a local Maven directory for use in integration tests.
+ *
+ * Using a local directory is beneficial because Maven Local
+ * [has some flaws](https://docs.gradle.org/8.6/userguide/declaring_repositories.html#sec:case-for-maven-local),
+ * and we can more tightly control what artifacts are published and are persisted.
+ *
+ * It's possible to publish to a local directory using a regular [PublishToMavenRepository] task,
+ * but when the project has a SNAPSHOT version the output will be timestamped, so Gradle will
+ * _always_ publish a new artifact. This causes two issues:
+ *
+ * - The publication tasks, and any test tasks, will _always_ be out-of-date, even if no code changed.
+ * - The local directory will endlessly grow in size
+ *   (which can be remedied by running `./gradlew clean`, but this is not ideal)
+ *
+ * To overcome this we manually set the system property `maven.repo.local` to a local directory.
+ * Gradle will respect this property, and publish artifacts to the local directory only when
+ * they have changed, improving performance.
+ */
+plugins {
+    base
+}
+
+/**
+ * Directory for the output of the current subproject's 'publishToMavenLocal'
+ */
+val currentProjectDevMavenRepo = gradle.rootProject.layout.buildDirectory.dir("dev-maven-repo")
+
+val devMavenPublishAttribute = Attribute.of("dev-maven-publish", String::class.java)
+
+dependencies {
+    attributesSchema {
+        attribute(devMavenPublishAttribute)
+    }
+}
+
+val publishToDevMavenRepo by tasks.registering {
+    description = "Publishes all Maven publications to the dev Maven repository."
+    group = PublishingPlugin.PUBLISH_TASK_GROUP
+}
+
+
+plugins.withType<MavenPublishPlugin>().all {
+    extensions
+        .getByType<PublishingExtension>()
+        .publications
+        .withType<MavenPublication>().all publication@{
+            val publicationName = [email protected]
+            val installTaskName = "publish${publicationName.uppercaseFirstChar()}PublicationToDevMavenRepo"
+
+            // Register a new publication task for each publication.
+            val installTask = tasks.register<PublishToMavenLocal>(installTaskName) {
+                description = "Publishes Maven publication '$publicationName' to the test Maven repository."
+                group = PublishingPlugin.PUBLISH_TASK_GROUP
+                publication = this@publication
+
+                val destinationDir = currentProjectDevMavenRepo.get().asFile
+                inputs.property("currentProjectDevMavenRepoPath", destinationDir.invariantSeparatorsPath)
+
+                doFirst {
+                    /**
+                     * `maven.repo.local` will set the destination directory for this [PublishToMavenLocal] task.
+                     *
+                     * @see org.gradle.api.internal.artifacts.mvnsettings.DefaultLocalMavenRepositoryLocator.getLocalMavenRepository
+                     */
+                    System.setProperty("maven.repo.local", destinationDir.absolutePath)
+                }
+            }
+
+            publishToDevMavenRepo.configure {
+                dependsOn(installTask)
+            }
+
+            tasks.check {
+                mustRunAfter(installTask)
+            }
+        }
+}
+
+
+val devPublication: Configuration by configurations.creating {
+    description = "Depend on project-local Dev Maven repositories"
+    declarable()
+}
+
+val devPublicationResolver: Configuration by configurations.creating {
+    description = "Resolve project-local Dev Maven repositories"
+    resolvable()
+    extendsFrom(devPublication)
+    attributes {
+        attribute(devMavenPublishAttribute, "devMavenRepo")
+    }
+}
+
+val devPublicationConsumable: Configuration by configurations.creating {
+    description = "Provide project-local Dev Maven repositories dependencies"
+    consumable()
+    attributes {
+        attribute(devMavenPublishAttribute, "devMavenRepo")
+    }
+    outgoing {
+        artifact(currentProjectDevMavenRepo) {
+            builtBy(publishToDevMavenRepo)
+        }
+    }
+}
+
+val devMavenPublishExtension = extensions.create<DevMavenPublishExtension>(
+    DEV_MAVEN_PUBLISH_EXTENSION_NAME,
+    // fetch Dev Maven Repos from the dependencies
+    devPublicationResolver.incoming.files,
+)

build-logic/src/main/kotlin/dokkabuild.publish-base.gradle.kts

@@ -3,8 +3,10 @@
  */
 
 plugins {
+    id("dokkabuild.base")
     `maven-publish`
     signing
+    id("dokkabuild.dev-maven-publish")
 }
 
 publishing {
@@ -33,13 +35,6 @@ publishing {
                 password = System.getenv("DOKKA_SPACE_PACKAGES_SECRET")
             }
         }
-        // Publish to a project-local Maven directory, for verification. To test, run:
-        // ./gradlew publishAllPublicationsToProjectLocalRepository
-        // and check $rootDir/build/maven-project-local
-        maven {
-            name = "projectLocal"
-            url = uri(rootProject.layout.buildDirectory.dir("maven-project-local"))
-        }
     }
 
     publications.withType<MavenPublication>().configureEach {

build-logic/src/main/kotlin/dokkabuild.test-integration.gradle.kts

@@ -61,7 +61,7 @@ val integrationTest by tasks.registering(NonCacheableIntegrationTest::class) {
     }
 
     environment("isExhaustive", dokkaBuild.integrationTestExhaustive.get())
-    
+
     testLogging {
         exceptionFormat = TestExceptionFormat.FULL
         events(TestLogEvent.SKIPPED, TestLogEvent.FAILED)

build-logic/src/main/kotlin/dokkabuild/DevMavenPublishExtension.kt

@@ -0,0 +1,60 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+package dokkabuild
+
+import org.gradle.api.Task
+import org.gradle.api.file.FileCollection
+import org.gradle.api.file.FileTree
+import org.gradle.api.tasks.PathSensitivity.RELATIVE
+import org.gradle.process.JavaForkOptions
+
+abstract class DevMavenPublishExtension(
+    /**
+     * Resolves Dev Maven repos from the current project's `devPublication` dependencies.
+     *
+     * Must only contain directories.
+     */
+    private val devMavenRepositories: FileCollection,
+) {
+
+    /**
+     * Files suitable for registering as a task input (as in, the files are reproducible-build compatible).
+     */
+    private val devMavenRepositoriesInputFiles: FileTree = devMavenRepositories
+        .asFileTree
+        .matching {
+            // Exclude Maven Metadata files because they contain timestamps,
+            // meaning tasks that use devMavenRepositories as an input will
+            // never be up-to-date.
+            // The Gradle Module Metadata contains the same information (and more),
+            // so no issues are expected.
+            exclude("**/maven-metadata*.xml")
+        }
+
+    /**
+     * Configures [task] to register [devMavenRepositories] as a task input,
+     * and (if possible) adds `devMavenRepository` as a [JavaForkOptions.systemProperty].
+     */
+    fun configureTask(task: Task) {
+        task.inputs.files(devMavenRepositoriesInputFiles)
+            .withPropertyName("devMavenPublish.devMavenRepositoriesInputFiles")
+            .withPathSensitivity(RELATIVE)
+
+        task.dependsOn(devMavenRepositories)
+
+        if (task is JavaForkOptions) {
+            task.doFirst("devMavenRepositories systemProperty") {
+                // workaround https://github.com/gradle/gradle/issues/24267
+                task.systemProperty(
+                    "devMavenRepositories",
+                    devMavenRepositories.joinToString(",") { it.canonicalFile.invariantSeparatorsPath }
+                )
+            }
+        }
+    }
+
+    companion object {
+        const val DEV_MAVEN_PUBLISH_EXTENSION_NAME = "devMavenPublish"
+    }
+}

build-logic/src/main/kotlin/dokkabuild/internal/gradleUtils.kt

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2014-2024 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package dokkabuild.internal
+
+import org.gradle.api.artifacts.Configuration
+
+/**
+ * Mark this [Configuration] as one that will be consumed by other subprojects.
+ *
+ * ```
+ * isCanBeResolved = false
+ * isCanBeConsumed = true
+ * isCanBeDeclared = false
+ * ```
+ */
+fun Configuration.consumable(
+    visible: Boolean = false
+) {
+    isVisible = visible
+    isCanBeResolved = false
+    isCanBeConsumed = true
+    isCanBeDeclared = false
+}
+
+/**
+ * Mark this [Configuration] as one that will consume artifacts from other subprojects (also known as 'resolving')
+ *
+ * ```
+ * isCanBeResolved = true
+ * isCanBeConsumed = false
+ * isCanBeDeclared = false
+ * ```
+ */
+fun Configuration.resolvable(
+    visible: Boolean = false
+) {
+    isVisible = visible
+    isCanBeResolved = true
+    isCanBeConsumed = false
+    isCanBeDeclared = false
+}
+
+/**
+ * Mark this [Configuration] as one that will be used to declare dependencies.
+ *
+ * ```
+ * isCanBeResolved = false
+ * isCanBeConsumed = false
+ * isCanBeDeclared = true
+ * ```
+ */
+fun Configuration.declarable(
+    visible: Boolean = false
+) {
+    isVisible = visible
+    isCanBeResolved = false
+    isCanBeConsumed = false
+    isCanBeDeclared = true
+}

dokka-integration-tests/gradle/build.gradle.kts

@@ -13,6 +13,7 @@ import org.jetbrains.kotlin.gradle.dsl.ExplicitApiMode.Disabled
 
 plugins {
     id("dokkabuild.kotlin-jvm")
+    id("dokkabuild.dev-maven-publish")
     `jvm-test-suite`
     `java-test-fixtures`
 }
@@ -27,6 +28,30 @@ dependencies {
     api(libs.junit.jupiterParams)
 
     api(gradleTestKit())
+
+    val dokkaVersion = project.version.toString()
+    // We're using Gradle included-builds and dependency substitution, so we
+    // need to use the Gradle project name, *not* the published Maven artifact-id
+    devPublication("org.jetbrains.dokka:plugin-all-modules-page:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:analysis-kotlin-api:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:analysis-kotlin-descriptors:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:analysis-kotlin-symbols:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:analysis-markdown-jb:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-android-documentation:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-base:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-base-test-utils:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:dokka-core:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-gfm:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-gfm-template-processing:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-javadoc:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-jekyll:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-jekyll-template-processing:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-kotlin-as-java:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-mathjax:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-templating:$dokkaVersion")
+    devPublication("org.jetbrains.dokka:plugin-versioning:$dokkaVersion")
+
+    devPublication("org.jetbrains.dokka:runner-gradle-plugin-classic:$dokkaVersion")
 }
 
 kotlin {
@@ -42,14 +67,7 @@ val aggregatingProject = gradle.includedBuild("dokka")
 val templateSettingsGradleKts = layout.projectDirectory.file("projects/template.settings.gradle.kts")
 val templateProjectsDir = layout.projectDirectory.dir("projects")
 
-tasks.integrationTestPreparation {
-    // TODO remove this in https://github.com/Kotlin/dokka/pull/3433
-    dependsOn(aggregatingProject.task(":publishToMavenLocal"))
-}
-
 tasks.withType<Test>().configureEach {
-    dependsOn(tasks.integrationTestPreparation)
-
     setForkEvery(1)
     maxHeapSize = "2G"
     dokkaBuild.integrationTestParallelism.orNull?.let { parallelism ->
@@ -69,7 +87,11 @@ tasks.withType<Test>().configureEach {
         dokkaBuild.isCI.map { isCi -> if (isCi) "ALWAYS" else "ON_SUCCESS" }.get(),
     )
 
-    environment("DOKKA_VERSION", project.version)
+    val dokkaVersion = provider { project.version.toString() }
+    inputs.property("dokkaVersion", dokkaVersion)
+    doFirst("set DOKKA_VERSION environment variable (workaround for https://github.com/gradle/gradle/issues/24267)") {
+        environment("DOKKA_VERSION", dokkaVersion.get())
+    }
 
     // environment() isn't Provider API compatible yet https://github.com/gradle/gradle/issues/11534
     dokkaBuild.integrationTestExhaustive.orNull?.let { exhaustive ->
@@ -87,8 +109,9 @@ tasks.withType<Test>().configureEach {
         showStackTraces = true
     }
 
-    // TODO remove this in https://github.com/Kotlin/dokka/pull/3433
-    doNotTrackState("uses artifacts from Maven Local")
+    // The tests produce report data and generated Dokka output.
+    // Always cache them so Gradle can skip running integration tests if nothing has changed.
+    outputs.cacheIf("always cache") { true }
 }
 
 testing {
@@ -200,6 +223,8 @@ fun TestingExtension.registerTestProjectSuite(
                     templateSettingsGradleKts.asFile.invariantSeparatorsPath,
                 )
 
+                devMavenPublish.configureTask(this)
+
                 if (jvm != null) {
                     javaLauncher = javaToolchains.launcherFor { languageVersion = jvm }
                 }