[Gradle] Schedule KotlinCompilation.source for removal in 2.0

Having only one SourceSet being associated with a KotlinCompilation
will simplify multiple code paths and prevents misconfiguration
from users.

^KT-58220 Verification Pending
See: KT-58234
See: KT-58235

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinCompilation.kt

@@ -13,9 +13,11 @@ import org.gradle.api.Project
 import org.gradle.api.attributes.AttributeContainer
 import org.gradle.api.attributes.HasAttributes
 import org.gradle.api.file.FileCollection
+import org.gradle.api.file.SourceDirectorySet
 import org.gradle.api.tasks.TaskProvider
 import org.jetbrains.kotlin.gradle.dsl.KotlinCommonOptionsDeprecated
 import org.jetbrains.kotlin.gradle.dsl.KotlinCompileDeprecated
+import org.jetbrains.kotlin.gradle.dsl.KotlinTargetHierarchyDsl
 import org.jetbrains.kotlin.gradle.tasks.KotlinCompilationTask
 import org.jetbrains.kotlin.tooling.core.HasMutableExtras
 
@@ -93,6 +95,45 @@ interface KotlinCompilation<out T : KotlinCommonOptionsDeprecated> : Named,
         const val TEST_COMPILATION_NAME = "test"
     }
 
+    /**
+     * Will add a [KotlinSourceSet] directly into this compilation.
+     * This method is deprecated and targets Kotlin 2.0 for its removal.
+     * After Kotlin 2.0 there will be exactly one SourceSet associated with a given Kotlin Compilation.
+     *
+     * In order to include other sources into the compilation, please build a hierarchy of Source Sets instead.
+     * See: [KotlinSourceSet.dependsOn] or [KotlinTargetHierarchyDsl].
+     * This approach is most applicable if
+     * - The sources can be shared for multiple compilations
+     * - The sources shall be analyzed in a different context than [defaultSourceSet]
+     * - The project uses multiplatform and sources shall provide expects
+     *
+     *
+     * Alternatively, when just including source files from another directory,
+     * the [SourceDirectorySet] from the [defaultSourceSet] can be used.
+     * This approach is most applicable if
+     *  - sources are not intended to be shared across multiple compilations
+     *  - sources shall be analyzed in the same context as other sources in the [defaultSourceSet]
+     *
+     * #### Example 1: Create a new 'utils' source set and make it available to the 'main' compilation:
+     * ```kotlin
+     * kotlin {
+     *     val compilation = target.compilations.getByName("main")
+     *     val utilsSourceSet = sourceSets.create("utils")
+     *     compilation.defaultSourceSet.dependsOn(utilsSourceSet)
+     * }
+     * ```
+     *
+     * #### Example 2: Add 'src/utils/kotlin' to the main SourceSet
+     * ```kotlin
+     * kotlin {
+     *     val compilation = target.compilations.getByName("main")
+     *     compilation.defaultSourceSet.kotlin.srcDir("src/utils/kotlin")
+     * }
+     * ```
+     * Further details:
+     * https://kotl.in/compilation-source-deprecation
+     */
+    @Deprecated("scheduled for removal with Kotlin 2.0")
     fun source(sourceSet: KotlinSourceSet)
 
     fun associateWith(other: KotlinCompilation<*>)

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/AbstractKotlinPlugin.kt

@@ -184,6 +184,7 @@ internal abstract class AbstractKotlinPlugin(
                 if (duplicateJavaSourceSetsAsKotlinSourceSets) {
                     val kotlinSourceSet = project.kotlinExtension.sourceSets.maybeCreate(kotlinCompilation.name)
                     kotlinSourceSet.kotlin.source(javaSourceSet.java)
+                    @Suppress("DEPRECATION")
                     kotlinCompilation.source(kotlinSourceSet)
                     @Suppress("DEPRECATION")
                     javaSourceSet.addConvention(kotlinSourceSetDslName, kotlinSourceSet)
@@ -196,6 +197,7 @@ internal abstract class AbstractKotlinPlugin(
             }
 
             kotlinTarget.compilations.all { kotlinCompilation ->
+                @Suppress("DEPRECATION")
                 kotlinCompilation.source(kotlinCompilation.defaultSourceSet)
             }
 

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/compilationImpl/KotlinCompilationImpl.kt

@@ -11,9 +11,9 @@ import org.gradle.api.Action
 import org.gradle.api.GradleException
 import org.gradle.api.attributes.AttributeContainer
 import org.gradle.api.file.FileCollection
+import org.gradle.api.file.SourceDirectorySet
 import org.gradle.api.tasks.TaskProvider
-import org.jetbrains.kotlin.gradle.dsl.KotlinCommonOptions
+import org.jetbrains.kotlin.gradle.dsl.*
-import org.jetbrains.kotlin.gradle.dsl.KotlinCompile
 import org.jetbrains.kotlin.gradle.plugin.*
 import org.jetbrains.kotlin.gradle.plugin.mpp.*
 import org.jetbrains.kotlin.gradle.plugin.mpp.InternalKotlinCompilation
@@ -90,6 +90,7 @@ internal class KotlinCompilationImpl constructor(
     override val kotlinSourceSets: ObservableSet<KotlinSourceSet>
         get() = sourceSets.kotlinSourceSets
 
+    @Deprecated("scheduled for removal with Kotlin 2.0")
     override fun source(sourceSet: KotlinSourceSet) {
         sourceSets.source(sourceSet)
     }

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/targets/android/AndroidProjectHandler.kt

@@ -203,9 +203,11 @@ internal class AndroidProjectHandler(
         }
 
         // Register the source only after the task is created, because the task is required for that:
+        @Suppress("DEPRECATION")
         compilation.source(defaultSourceSet)
 
         compilation.androidVariant.forEachKotlinSourceSet(project) { kotlinSourceSet ->
+            @Suppress("DEPRECATION")
             compilation.source(kotlinSourceSet)
         }
     }

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/targets/js/KotlinJsTargetConfigurator.kt

@@ -61,6 +61,7 @@ open class KotlinJsTargetConfigurator :
         val project = target.project
 
         target.compilations.all { compilation ->
+            @Suppress("DEPRECATION")
             compilation.source(compilation.defaultSourceSet)
 
             configureResourceProcessing(

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/targets/metadata/KotlinMetadataTargetPreset.kt

@@ -54,6 +54,7 @@ class KotlinMetadataTargetPreset(
             val mainCompilation = compilations.getByName(KotlinCompilation.MAIN_COMPILATION_NAME)
             val commonMainSourceSet = project.kotlinExtension.sourceSets.getByName(KotlinSourceSet.COMMON_MAIN_SOURCE_SET_NAME)
 
+            @Suppress("DEPRECATION")
             mainCompilation.source(commonMainSourceSet)
 
             project.whenEvaluated {

libraries/tools/kotlin-gradle-plugin/src/functionalTest/kotlin/org/jetbrains/kotlin/gradle/unitTests/SourceSetCommonizerTargetTest.kt

@@ -217,6 +217,7 @@ class SourceSetCommonizerTargetTest {
         val nativeMain = kotlin.sourceSets.create("nativeMain")
 
         listOf(linux1, linux2).forEach { target ->
+            @Suppress("DEPRECATION")
             target.compilations.getByName("main").source(nativeMain)
         }