azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[Gradle] Move KotlinHierarchyDsl documentation into KotlinHierarchyDsl.kt

Browse Source 
^KT-58676 Verification Pending
This commit is contained in:
Sebastian Sellmair
2023-06-22 09:47:05 +02:00
committed by Space Team
parent a03fb02af3
commit 6d4dbfae28
2 changed files with 122 additions and 119 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinHierarchyDsl.kt
+121
View File
@@ -8,13 +8,134 @@ package org.jetbrains.kotlin.gradle.dsl
import org.jetbrains.kotlin.gradle.ExperimentalKotlinGradlePluginApi
import org.jetbrains.kotlin.gradle.plugin.KotlinHierarchyBuilder
import org.jetbrains.kotlin.gradle.plugin.KotlinHierarchyTemplate
import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSetTree
interface KotlinHierarchyDsl {
/**
* Will apply the given [template] to the project.
*
* #### Example: Manually apply the default hierarchy
* (see KotlinMultiplatformExtension.applyDefaultHierarchyTemplate)
* ```kotlin
* kotlin {
* applyHierarchyTemplate(KotlinHierarchyTemplate.default)
* iosX64()
* iosArm64()
* iosSimulatorArm64()
* linuxX64()
* // ...
* }
* ```
*/
fun applyHierarchyTemplate(template: KotlinHierarchyTemplate)
/**
* Similar to [applyDefaultHierarchyTemplate], but allows to extend the provided template
*
* #### Example 2: Adding custom groups (Experimental)
* Let's imagine we would additionally like to share code between linux and apple (unixLike)
*
* ```kotlin
* kotlin {
* applyHierarchyTemplate(KotlinHierarchyTemplate.default) {
* group("native") { // <- we can re-declare already existing groups and connect children to it!
* group("unixLike") {
* withLinux()
* withApple()
* }
* }
* }
* }
* ```
*/
@ExperimentalKotlinGradlePluginApi
fun applyHierarchyTemplate(template: KotlinHierarchyTemplate, extension: KotlinHierarchyBuilder.Root.() -> Unit)
/**
* 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
* applyHierarchyTemplate {
* common {
* withJvm()
* group("ios") {
* withIos()
* }
* }
* }
* ```
*
* Will create two [KotlinSourceSetTree] 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
* applyHierarchyTemplate {
* 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' KotlinSourceSetTree:
*
* ```
* commonMain
* |
* +------------+----------+
* | |
* frontendMain appleMain
* | |
* +---------+------------+-----------+----------+
* | | |
* jvmMain iosMain macosX64Main
* |
* |
* +----+----+
* | |
* iosX64Main iosArm64Main
* ```
*/
@ExperimentalKotlinGradlePluginApi
fun applyHierarchyTemplate(template: KotlinHierarchyBuilder.Root.() -> Unit)
}
libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/dsl/KotlinMultiplatformExtension.kt
+1 -119
View File
@@ -101,140 +101,22 @@ abstract class KotlinMultiplatformExtension
*/
fun applyDefaultHierarchyTemplate() = applyHierarchyTemplate(KotlinHierarchyTemplate.default)
/**
* Will apply the given [template] to the project.
*
* ### Example: Manually apply the default hierarchy (see [applyDefaultHierarchyTemplate])
* ```kotlin
* kotlin {
* applyHierarchyTemplate(KotlinHierarchyTemplate.default)
* iosX64()
* iosArm64()
* iosSimulatorArm64()
* linuxX64()
* // ...
* }
* ```
*/
@ExperimentalKotlinGradlePluginApi
override fun applyHierarchyTemplate(template: KotlinHierarchyTemplate) {
hierarchy.applyHierarchyTemplate(template)
}
/**
* Similar to [applyDefaultHierarchyTemplate], but allows to extend the provided template
*
* #### Example 2: Adding custom groups (Experimental)
* Let's imagine we would additionally like to share code between linux and apple (unixLike)
*
* ```kotlin
* kotlin {
* applyHierarchyTemplate(KotlinHierarchyTemplate.default) {
* group("native") { // <- we can re-declare already existing groups and connect children to it!
* group("unixLike") {
* withLinux()
* withApple()
* }
* }
* }
* }
* ```
*/
@ExperimentalKotlinGradlePluginApi
override fun applyHierarchyTemplate(template: KotlinHierarchyTemplate, extension: KotlinHierarchyBuilder.Root.() -> Unit) {
hierarchy.applyHierarchyTemplate(template, extension)
}
/**
* 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
* applyHierarchyTemplate {
* common {
* withJvm()
* group("ios") {
* withIos()
* }
* }
* }
* ```
*
* Will create two [KotlinSourceSetTree] 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
* applyHierarchyTemplate {
* 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' KotlinSourceSetTree:
*
* ```
* commonMain
* |
* +------------+----------+
* | |
* frontendMain appleMain
* | |
* +---------+------------+-----------+----------+
* | | |
* jvmMain iosMain macosX64Main
* |
* |
* +----+----+
* | |
* iosX64Main iosArm64Main
* ```
*/
@ExperimentalKotlinGradlePluginApi
override fun applyHierarchyTemplate(template: KotlinHierarchyBuilder.Root.() -> Unit) {
hierarchy.applyHierarchyTemplate(template)
}
@Suppress("unused") // DSL
val testableTargets: NamedDomainObjectCollection<KotlinTargetWithTests<*, *>>
get() = targets.withType(KotlinTargetWithTests::class.java)