Skip to content

Migrate to DGPv2 #4436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jun 25, 2025
Merged

Migrate to DGPv2 #4436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
4d6ac73
Workaround to make project importable.
qwwdfsad Oct 22, 2024
b4c4f46
Migration to DGPv2
qwwdfsad Oct 23, 2024
8d1525e
TODO
qwwdfsad Oct 23, 2024
8d3cc55
Update buildSrc/src/main/kotlin/dokka-conventions.gradle.kts
qwwdfsad Oct 23, 2024
7c6e5ff
Dokka 2.0.0
whyoleg May 15, 2025
1c9b082
Rename function back to it's original name to reduce diff
whyoleg May 15, 2025
f2167c4
Remove workaround for KT-71784
whyoleg May 15, 2025
5c3a04d
Simplify templatesDir configuring
whyoleg May 15, 2025
63e88d4
Cleanup `dokka-convention`
whyoleg May 15, 2025
c5f2051
Drop local package list as it's better to use remote one
whyoleg May 15, 2025
06b0df2
Fix external links in rx modules
whyoleg May 15, 2025
a179bb7
Fix knit
whyoleg May 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions buildSrc/src/main/kotlin/Dokka.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import org.gradle.api.*
import org.gradle.api.publish.PublishingExtension
import org.gradle.kotlin.dsl.*
import org.jetbrains.dokka.gradle.*
import org.jetbrains.dokka.gradle.DokkaExtension
import java.io.*
import java.net.*

Expand All @@ -11,11 +12,11 @@ fun Project.externalDocumentationLink(
url: String,
packageList: File = projectDir.resolve("package.list")
) {
tasks.withType<AbstractDokkaLeafTask>().configureEach {
extensions.configure<DokkaExtension> {
dokkaSourceSets.configureEach {
externalDocumentationLink {
this.url = URL(url)
packageListUrl = packageList.toPath().toUri().toURL()
externalDocumentationLinks.register("api") {
this.url = URI.create(url)
this.packageListUrl = packageList.toURI()
}
}
}
Expand Down
8 changes: 4 additions & 4 deletions buildSrc/src/main/kotlin/UnpackAar.kt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@ import java.util.zip.ZipFile
val artifactType = Attribute.of("artifactType", String::class.java)
val unpackedAar = Attribute.of("unpackedAar", Boolean::class.javaObjectType)

fun Project.configureAar() = configurations.configureEach {
afterEvaluate {
if (isCanBeResolved && !isCanBeConsumed) {
fun Project.configureAar() {
configurations
.matching { it.isCanBeResolved && !it.isCanBeConsumed }
.configureEach {
attributes.attribute(unpackedAar, true) // request all AARs to be unpacked
}
}
}

fun DependencyHandlerScope.configureAarUnpacking() {
Expand Down
77 changes: 23 additions & 54 deletions buildSrc/src/main/kotlin/dokka-conventions.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
import org.jetbrains.dokka.gradle.*
import java.net.*


Expand All @@ -7,75 +6,45 @@ plugins {
}

val knit_version: String by project
private val projetsWithoutDokka = unpublished + "kotlinx-coroutines-bom" + jdk8ObsoleteModule
private val coreModuleDocsUrl = "https://kotlinlang.org/api/kotlinx.coroutines/$coreModule/"
private val coreModuleDocsPackageList = "$projectDir/kotlinx-coroutines-core/build/dokka/htmlPartial/package-list"
private val projectsWithoutDokka = unpublished + "kotlinx-coroutines-bom" + jdk8ObsoleteModule
private val subprojectWithDokka = subprojects.filterNot { projectsWithoutDokka.contains(it.name) }

configure(subprojects.filterNot { projetsWithoutDokka.contains(it.name) }) {
configure(subprojectWithDokka) {
apply(plugin = "org.jetbrains.dokka")
configurePathsaver()
configureDokkaTemplatesDir()
condigureDokkaSetup()
configureExternalLinks()
}

// Setup top-level 'dokkaHtmlMultiModule' with templates
tasks.withType<DokkaMultiModuleTask>().named("dokkaHtmlMultiModule") {
setupDokkaTemplatesDir(this)
}
// For top-level multimodule collection
configurePathsaver()
configureDokkaTemplatesDir()

dependencies {
// Add explicit dependency between Dokka and Knit plugin
add("dokkaHtmlMultiModulePlugin", "org.jetbrains.kotlinx:dokka-pathsaver-plugin:$knit_version")
subprojectWithDokka.forEach {
dokka(it)
}
}

// Dependencies for Knit processing: Knit plugin to work with Dokka
private fun Project.configurePathsaver() {
tasks.withType(DokkaTaskPartial::class).configureEach {
dependencies {
plugins("org.jetbrains.kotlinx:dokka-pathsaver-plugin:$knit_version")
}
dependencies {
dokkaPlugin("org.jetbrains.kotlinx:dokka-pathsaver-plugin:$knit_version")
}
}

// Configure Dokka setup
private fun Project.condigureDokkaSetup() {
tasks.withType(DokkaTaskPartial::class).configureEach {
suppressInheritedMembers = true
setupDokkaTemplatesDir(this)

dokka {
dokkaPublications.configureEach {
suppressInheritedMembers = true
}
dokkaSourceSets.configureEach {
jdkVersion = 11
includes.from("README.md")
noStdlibLink = true

externalDocumentationLink {
url = URL("https://kotlinlang.org/api/latest/jvm/stdlib/")
packageListUrl = rootProject.projectDir.toPath().resolve("site/stdlib.package.list").toUri().toURL()
}

// Something suspicious to figure out, probably legacy of earlier days
if (!project.isMultiplatform) {
dependsOn(project.configurations["compileClasspath"])
}
}

// Source links
dokkaSourceSets.configureEach {
sourceLink {
localDirectory = rootDir
remoteUrl = URL("https://github.com/kotlin/kotlinx.coroutines/tree/master")
remoteLineSuffix ="#L"
}
}
}
}

private fun Project.configureExternalLinks() {
tasks.withType<DokkaTaskPartial>() {
dokkaSourceSets.configureEach {
externalDocumentationLink {
url = URL(coreModuleDocsUrl)
packageListUrl = File(coreModuleDocsPackageList).toURI().toURL()
remoteUrl("https://github.com/kotlin/kotlinx.coroutines/tree/master")
}
}
}
Expand All @@ -90,10 +59,10 @@ private fun Project.configureExternalLinks() {
* - Template setup: https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/builds/apiReferences/kotlinx/coroutines/KotlinxCoroutinesPrepareDokkaTemplates.kt
* - Templates repository: https://github.com/JetBrains/kotlin-web-site/tree/master/dokka-templates
*/
private fun Project.setupDokkaTemplatesDir(dokkaTask: AbstractDokkaTask) {
dokkaTask.pluginsMapConfiguration = mapOf(
"org.jetbrains.dokka.base.DokkaBase" to """{ "templatesDir" : "${
project.rootProject.projectDir.toString().replace('\\', '/')
}/dokka-templates" }"""
)
private fun Project.configureDokkaTemplatesDir() {
dokka {
pluginsConfiguration.html {
templatesDir = rootDir.resolve("dokka-templates")
}
}
}
14 changes: 4 additions & 10 deletions buildSrc/src/main/kotlin/knit-conventions.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,10 @@ plugins {
knit {
siteRoot = "https://kotlinlang.org/api/kotlinx.coroutines"
moduleRoots = listOf(".", "integration", "reactive", "ui")
moduleDocs = "build/dokka/htmlPartial"
dokkaMultiModuleRoot = "build/dokka/htmlMultiModule/"
moduleDocs = "build/dokka-module/html/module"
dokkaMultiModuleRoot = "build/dokka/html/"
}

tasks.named("knitPrepare").configure {
val knitTask = this
// In order for knit to operate, it should depend on and collect
// all Dokka outputs from each module
allprojects {
val dokkaTasks = tasks.matching { it.name == "dokkaHtmlMultiModule" }
knitTask.dependsOn(dokkaTasks)
}
tasks.named("knitPrepare") {
dependsOn("dokkaGenerate")
}
5 changes: 4 additions & 1 deletion gradle.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,10 @@ junit_version=4.12
junit5_version=5.7.0
knit_version=0.5.0
lincheck_version=2.18.1
dokka_version=1.9.20
dokka_version=2.0.0
org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
org.jetbrains.dokka.experimental.gradle.pluginMode.nowarn=true

byte_buddy_version=1.10.9
reactor_version=3.4.1
reactor_docs_version=3.4.5
Expand Down
3 changes: 2 additions & 1 deletion kotlinx-coroutines-core/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import org.gradle.kotlin.dsl.*
import org.gradle.kotlin.dsl.withType
import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
import org.jetbrains.dokka.gradle.tasks.DokkaBaseTask
import org.jetbrains.kotlin.gradle.plugin.mpp.*
import org.jetbrains.kotlin.gradle.targets.native.tasks.*
import org.jetbrains.kotlin.gradle.tasks.*
Expand Down Expand Up @@ -287,7 +288,7 @@ artifacts {
}

// Workaround for https://github.com/Kotlin/dokka/issues/1833: make implicit dependency explicit
tasks.named("dokkaHtmlPartial") {
tasks.withType<DokkaBaseTask>() {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@adam-enko, this is still required. Could you check what happens here?

Copy link
Member

@adam-enko adam-enko Jun 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked out your branch, commented out this code, and ran gradle :kotlinx-coroutines-core:dokkaGenerate but didn't see a problem. How can I trigger the error?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, okay, I needed to run gradle :dokkaGenerate.

> Task :kotlinx-coroutines-core:jvmJar FAILED

[Incubating] Problems report is available at: file:///Users/dev/projects/jetbrains/kotlin/kotlinx.coroutines/build/reports/problems/problems-report.html
42 actionable tasks: 11 executed, 31 up-to-date

FAILURE: Build failed with an exception.

* What went wrong:
A problem was found with the configuration of task ':kotlinx-coroutines-core:jvmJar' (type 'Jar').
  - Gradle detected a problem with the following location: '/Users/dev/projects/jetbrains/kotlin/kotlinx.coroutines/kotlinx-coroutines-core/build/libs/kotlinx-coroutines-core-jvm-1.10.2-SNAPSHOT.jar'.
    
    Reason: Task ':kotlinx-coroutines-core:dokkaGenerateModuleHtml' uses this output of task ':kotlinx-coroutines-core:jvmJar' without declaring an explicit or implicit dependency. This can lead to incorrect results being produced, depending on what order the tasks are executed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what the problem is, and it's hard to figure out.

I'm just speculating, but maybe somehow DGP automatically registers the Dokka SourceSets before KGP has finished creating the jvmJar task, and so the task dependencies aren't correct. I don't know how this could happen, but it seems to describe the result.

If I were to guess, it's because the buildscripts are using cross-project configuration (allproject/subproject) and internal Gradle utilities (org.gradle.kotlin.dsl.support.delegates.ProjectDelegate#configure), so the plugins aren't applied in the correct order.

I think the only way to fix this is to update the buildscripts so they don't use discouraged practices.

Copy link
Contributor Author

@whyoleg whyoleg Jun 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand, :kotlinx-coroutines-core:dokkaGenerateModuleHtml should not depend at all on :kotlinx-coroutines-core:jvmJar in main source sets, because it should rely on sources of the current module + classpath of dependencies.
Another idea could be that jvmJar is needed for one of the test source sets, which is created by KGP, and so added as a Dokka source set, but those are suppressed, and I thought that it should not affect the inputs of the dokkaGenerateModuleHtml task. But maybe I'm wrong, and even if the source set is suppressed, it will affect inputs?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In any case, I would say it's not blocking the migration to DGPv2

dependsOn(jvmJar)
}

Expand Down
12 changes: 1 addition & 11 deletions reactive/kotlinx-coroutines-rx2/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,10 @@
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import java.net.*

dependencies {
api(project(":kotlinx-coroutines-reactive"))
testImplementation("org.reactivestreams:reactive-streams-tck:${version("reactive_streams")}")
api("io.reactivex.rxjava2:rxjava:${version("rxjava2")}")
}

tasks.withType(DokkaTaskPartial::class) {
dokkaSourceSets.configureEach {
externalDocumentationLink {
url = URL("http://reactivex.io/RxJava/2.x/javadoc/")
packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
}
}
}
externalDocumentationLink("http://reactivex.io/RxJava/2.x/javadoc/")

val testNG by tasks.registering(Test::class) {
useTestNG()
Expand Down
12 changes: 1 addition & 11 deletions reactive/kotlinx-coroutines-rx3/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,10 @@
import org.jetbrains.dokka.gradle.DokkaTaskPartial
import java.net.*

dependencies {
api(project(":kotlinx-coroutines-reactive"))
testImplementation("org.reactivestreams:reactive-streams-tck:${version("reactive_streams")}")
api("io.reactivex.rxjava3:rxjava:${version("rxjava3")}")
}

tasks.withType(DokkaTaskPartial::class) {
dokkaSourceSets.configureEach {
externalDocumentationLink {
url = URL("https://reactivex.io/RxJava/3.x/javadoc/")
packageListUrl = projectDir.toPath().resolve("package.list").toUri().toURL()
}
}
}
externalDocumentationLink("http://reactivex.io/RxJava/3.x/javadoc/")

val testNG by tasks.registering(Test::class) {
useTestNG()
Expand Down
Loading