From 71189e204993cec632414e40b1f627df39f60ef3 Mon Sep 17 00:00:00 2001 From: Sebastian Sellmair Date: Mon, 24 Apr 2023 18:16:22 +0200 Subject: [PATCH] [Gradle] Add documentation to KotlinTargetHierarchyDsl.custom ^KT-58209 Verification Pending --- .../gradle/dsl/KotlinTargetHierarchyDsl.kt | 84 +++++++++++++++++++ .../unitTests/KotlinTargetHierarchyDslTest.kt | 57 +++++++++++++ 2 files changed, 141 insertions(+) diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTargetHierarchyDsl.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTargetHierarchyDsl.kt index ff9105f0d4d..c9034aabc5f 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTargetHierarchyDsl.kt +++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinTargetHierarchyDsl.kt @@ -85,6 +85,90 @@ interface KotlinTargetHierarchyDsl { */ fun default(describeExtension: (KotlinTargetHierarchyBuilder.Root.() -> Unit)? = null) + /** + * Allows to create a fully custom hierarchy (no defaults applied) + * Note: Using the custom hierarchy will also require to set the edges to 'commonMain' and 'commonTest' SourceSets by + * using the `common` group. + * + * #### Example 1: + * Sharing code between iOS and a jvmTarget: + * ```kotlin + * targetHierarchy.custom { + * common { + * withJvm() + * group("ios") { + * withIos() + * } + * } + * } + * ``` + * + * Will create two [SourceSetTree] using the 'common' and 'ios' groups, applied on the "test" and "main" compilations: + * When the following targets are specified: + * - jvm() + * - iosX64() + * - iosArm64() + * ``` + * "main" "test" + * commonMain commonTest + * | | + * | | + * +----------+----------+ +----------+----------+ + * | | | | + * iosMain jvmMain iosTest jvmTest + * | | + * +----+-----+ +----+-----+ + * | | | | + * iosX64Main iosArm64Main iosX64Test iosArm64Test + * ``` + * + * #### Example 2: Creating a 'diamond structure' + * ```kotlin + * targetHierarchy.custom { + * common { + * group("ios") { + * withIos() + * } + * + * group("frontend") { + * withJvm() + * group("ios") // <- ! We can again reference the 'ios' group + * } + * + * group("apple") { + * withMacos() + * group("ios") // <- ! We can again reference the 'ios' group + * } + * } + * } + * ``` + * + * In this case, the _group_ "ios" can be created with 'group("ios")' and later referenced with the same construction to build + * the tree. Applying the descriptor from the example to the following targets: + * - iosX64() + * - iosArm64() + * - macosX64() + * - jvm() + * + * will create the following 'main' SourceSetTree: + * + * ``` + * commonMain + * | + * +------------+----------+ + * | | + * frontendMain appleMain + * | | + * +---------+------------+-----------+----------+ + * | | | + * jvmMain iosMain macosX64Main + * | + * | + * +----+----+ + * | | + * iosX64Main iosArm64Main + * ``` + */ fun custom(describe: KotlinTargetHierarchyBuilder.Root.() -> Unit) @ExperimentalKotlinGradlePluginApi diff --git a/libraries/tools/kotlin-gradle-plugin/src/functionalTest/kotlin/org/jetbrains/kotlin/gradle/unitTests/KotlinTargetHierarchyDslTest.kt b/libraries/tools/kotlin-gradle-plugin/src/functionalTest/kotlin/org/jetbrains/kotlin/gradle/unitTests/KotlinTargetHierarchyDslTest.kt index 9948d1682c0..50abc866862 100644 --- a/libraries/tools/kotlin-gradle-plugin/src/functionalTest/kotlin/org/jetbrains/kotlin/gradle/unitTests/KotlinTargetHierarchyDslTest.kt +++ b/libraries/tools/kotlin-gradle-plugin/src/functionalTest/kotlin/org/jetbrains/kotlin/gradle/unitTests/KotlinTargetHierarchyDslTest.kt @@ -388,6 +388,63 @@ class KotlinTargetHierarchyDslTest { ) } + /** + * Example from the documentation is supposed to create + * commonMain + * | + * +------------+----------+ + * | | + * frontendMain appleMain + * | | + * +---------+------------+-----------+----------+ + * | | | + * jvmMain iosMain macosX64Main + * | + * | + * +----+----+ + * | | + * iosX64Main iosArm64Main + */ + @Test + fun `test - diamond hierarchy from documentation example`() { + kotlin.targetHierarchy.custom { + common { + group("ios") { + withIos() + } + group("frontend") { + withJvm() + group("ios") // <- ! We can again reference the 'ios' group + } + group("apple") { + withMacos() + group("ios") // <- ! We can again reference the 'ios' group + } + } + } + + kotlin.iosX64() + kotlin.iosArm64() + kotlin.macosX64() + kotlin.jvm() + + assertEquals( + stringSetOf("frontendMain", "appleMain"), kotlin.dependingSourceSetNames("commonMain") + ) + + assertEquals( + stringSetOf("jvmMain", "iosMain"), kotlin.dependingSourceSetNames("frontendMain") + ) + + assertEquals( + stringSetOf("macosX64Main", "iosMain"), kotlin.dependingSourceSetNames("appleMain") + ) + + assertEquals( + stringSetOf("iosArm64Main", "iosX64Main"), kotlin.dependingSourceSetNames("iosMain") + ) + } + } private fun KotlinMultiplatformExtension.dependingSourceSetNames(sourceSetName: String) =