From 55cc2e5e4200c19d70b35ca440927e2d683a48e4 Mon Sep 17 00:00:00 2001 From: Sebastian Sellmair Date: Tue, 18 Apr 2023 15:35:37 +0200 Subject: [PATCH] [Gradle] ExternalTargetApi: Check-in/Document ExternalKotlinTargetDescriptor KT-55524 --- .../api/kotlin-gradle-plugin.api | 4 ++ .../ExternalKotlinTargetDescriptor.kt | 48 +++++++++++++++++++ 2 files changed, 52 insertions(+) diff --git a/libraries/tools/kotlin-gradle-plugin/api/kotlin-gradle-plugin.api b/libraries/tools/kotlin-gradle-plugin/api/kotlin-gradle-plugin.api index bee7ac90851..62d75c3fd04 100644 --- a/libraries/tools/kotlin-gradle-plugin/api/kotlin-gradle-plugin.api +++ b/libraries/tools/kotlin-gradle-plugin/api/kotlin-gradle-plugin.api @@ -255,6 +255,10 @@ public abstract interface class org/jetbrains/kotlin/gradle/plugin/mpp/external/ public abstract fun getTargetName ()Ljava/lang/String; } +public abstract interface class org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinTargetDescriptor$TargetFactory { + public abstract fun create (Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/DecoratedExternalKotlinTarget$Delegate;)Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/DecoratedExternalKotlinTarget; +} + public final class org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinTargetDescriptorBuilder { public final fun configure (Lkotlin/jvm/functions/Function1;)V public final fun configureIdeImport (Lkotlin/jvm/functions/Function1;)V diff --git a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinTargetDescriptor.kt b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinTargetDescriptor.kt index 6b48e0bb40d..87be9ae7700 100644 --- a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinTargetDescriptor.kt +++ b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinTargetDescriptor.kt @@ -3,6 +3,8 @@ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file. */ +@file:Suppress("MemberVisibilityCanBePrivate") + package org.jetbrains.kotlin.gradle.plugin.mpp.external import org.jetbrains.kotlin.gradle.ExternalKotlinTargetApi @@ -11,9 +13,16 @@ import org.jetbrains.kotlin.gradle.plugin.ide.IdeMultiplatformImport import org.jetbrains.kotlin.gradle.plugin.mpp.external.ExternalKotlinTargetDescriptor.TargetFactory import kotlin.properties.Delegates +/** + * Descriptor used by the Kotlin Gradle Plugin to build a corresponding [ExternalKotlinTargetImpl] from. + * This interface is *not stable for implementation* and will become sealed in the future! + * + * Use the `ExternalKotlinTargetDescriptor { }` factory function to create a new instance using a builder pattern + */ @ExternalKotlinTargetApi interface ExternalKotlinTargetDescriptor { + @ExternalKotlinTargetApi fun interface TargetFactory { fun create(target: DecoratedExternalKotlinTarget.Delegate): T } @@ -32,6 +41,11 @@ interface ExternalKotlinTargetDescriptor { val configureIdeImport: (IdeMultiplatformImport.() -> Unit)? } +/** + * Creates a new [ExternalKotlinTargetDescriptor] using the builder pattern. + * There are some required properties that have to be set. + * Check [ExternalKotlinTargetDescriptorBuilder] for further details. + */ @ExternalKotlinTargetApi fun ExternalKotlinTargetDescriptor( configure: ExternalKotlinTargetDescriptorBuilder.() -> Unit @@ -39,6 +53,16 @@ fun ExternalKotlinTargetDescriptor( return ExternalKotlinTargetDescriptorBuilder().also(configure).build() } +/** + * Mutable version of [ExternalKotlinTargetDescriptor] + * The following properties have to be specified: + * - [targetName] + * - [platformType] + * - [targetFactory] + * + * Properties added in future Kotlin Gradle Plugin releases will be added using a default value, but + * a warning might be emitted if not specified. + */ @ExternalKotlinTargetApi class ExternalKotlinTargetDescriptorBuilder internal constructor() { var targetName: String by Delegates.notNull() @@ -60,16 +84,40 @@ class ExternalKotlinTargetDescriptorBuilder i val runtimeElementsPublished: ExternalKotlinTargetConfigurationDescriptorBuilder = ExternalKotlinTargetConfigurationDescriptorBuilder() + /** + * Generic configuration that will be invoked when building the target. + * This configuration is called right after creating the instance and before + * publishing the target to all subscribers of `kotlin.targets.all {}` + */ var configure: ((T) -> Unit)? = null + /** + * Generic configuration that will be invoked when building the target. + * This configuration is called right after creating the instance and before + * publishing the target to all subscribers of `kotlin.targets.all {}` + */ fun configure(action: (T) -> Unit) { val configure = this.configure if (configure == null) this.configure = action else this.configure = { configure(it); action(it) } } + /** + * Main entrance of configuring the ide import: + * The [IdeMultiplatformImport] instance passed to this function shall + * not be captured and used outside of this block. + * + * The [IdeMultiplatformImport] instance shall not be retrieved any other way than using this function. + */ var configureIdeImport: (IdeMultiplatformImport.() -> Unit)? = null + /** + * Main entrance of configuring the ide import: + * The [IdeMultiplatformImport] instance passed to this function shall + * not be captured and used outside of this block. + * + * The [IdeMultiplatformImport] instance shall not be retrieved any other way than using this function. + */ fun configureIdeImport(action: IdeMultiplatformImport.() -> Unit) { val configureIdeImport = this.configureIdeImport if (configureIdeImport == null) this.configureIdeImport = action