[KGP] Introduce Incremental Compilation Feature Toggles

Makes it easier to introduce a Gradle property for configuring
IncrementalCompilerRunner.

^KT-64513 Fixed
^KT-63837 In Progress


Merge-request: KT-MR-13671
Merged-by: Evgenii Mazhukin <evgenii.mazhukin@jetbrains.com>

build-common/src/org/jetbrains/kotlin/incremental/IncrementalCompilationContext.kt

@@ -23,12 +23,7 @@ class IncrementalCompilationContext(
      * Controls whether changes in lookup cache should be tracked. Required for the classpath snapshots based IC approach
      */
     val trackChangesInLookupCache: Boolean = false,
-    /**
-     * Controls whether any changes should be propagated to FS until we decide that the compilation is successful or not
-     *
-     * Required for optimizing Gradle side outputs backup
-     */
-    val keepIncrementalCompilationCachesInMemory: Boolean = false,
+    val icFeatures: IncrementalCompilationFeatures = IncrementalCompilationFeatures.DEFAULT_CONFIGURATION,
 ) {
     @Deprecated("This constructor is scheduled to be removed. KSP is using it")
     constructor(
@@ -45,7 +40,9 @@ class IncrementalCompilationContext(
         transaction,
         reporter,
         trackChangesInLookupCache,
-        keepIncrementalCompilationCachesInMemory
+        IncrementalCompilationFeatures.DEFAULT_CONFIGURATION.copy(
+            keepIncrementalCompilationCachesInMemory = keepIncrementalCompilationCachesInMemory
+        ),
     )
 
     val fileDescriptorForSourceFiles: KeyDescriptor<File> = pathConverterForSourceFiles.getFileDescriptor()

build-common/src/org/jetbrains/kotlin/incremental/IncrementalCompilationFeatures.kt

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2010-2023 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package org.jetbrains.kotlin.incremental
+
+import java.io.Serializable
+
+/**
+ * Lists configurable feature toggles for Incremental Compilation.
+ * Obsolete features might be removed, so it's not recommended
+ * to use this outside of Kotlin repository.
+ *
+ * It's intended to be used across all build systems and target platforms.
+ * Then, for example, if we're ready to port a feature from one platform to another,
+ * we just have to initialize the build system-dependent property, and the value
+ * would be available at the use site without any additional boilerplate.
+ *
+ * To add a new feature toggle, consider this checklist:
+ *
+ * 1. Gradle input: see [AbstractKotlinCompile.getIncrementalCompilationFeatures].
+ *    Platform-agnostic properties should be the default, but you can extend one of the subclasses, if needed.
+ *    If new property might affect the result of compilation, annotate it with @Input.
+ * 2. Gradle.properties support: declare the property in [org.jetbrains.kotlin.gradle.plugin.PropertiesProvider].
+ *    Add its use in [org.jetbrains.kotlin.gradle.tasks.configuration.AbstractKotlinCompileConfig] or one of its subclasses (see step 1).
+ * 3. Build Tools Api, KGP to Interface part: see [BuildToolsApiCompilationWork.performCompilation]
+ *    You need to update both the interface [IncrementalJvmCompilationConfiguration] and its implementation(s).
+ * 4. Build Tools Api, Interface to Implementation part: see [ICConfiguration.extractIncrementalCompilationFeatures] and its uses.
+ *    Most likely you just need to update the `extract` method.
+ * 5. Maven - TODO(emazhukin) will do and describe in KT-63837
+ * 6. Gradle Integration Tests - add new option to [org.jetbrains.kotlin.gradle.testbase.BuildOptions]
+ */
+data class IncrementalCompilationFeatures(
+    /**
+     * Snapshot-based cross-module IC if true, BuildHistory-based if false.
+     * Snapshot-based IC is only available in JVM.
+     */
+    val withAbiSnapshot: Boolean = false,
+    /**
+     * Enables [RecoverableCompilationTransaction] for better restoration of build outputs
+     * in case of a build error.
+     */
+    val preciseCompilationResultsBackup: Boolean = false,
+    /**
+     * If enabled, IC caches are flushed to FS only when the compilation is successful.
+     * Optimizes outputs backup on Gradle side.
+     * Requires [preciseCompilationResultsBackup]
+     */
+    val keepIncrementalCompilationCachesInMemory: Boolean = false,
+) : Serializable {
+
+    companion object {
+        val DEFAULT_CONFIGURATION = IncrementalCompilationFeatures()
+
+        const val serialVersionUID: Long = 0
+    }
+}

build-common/src/org/jetbrains/kotlin/incremental/storage/LazyStorage.kt

@@ -153,7 +153,7 @@ fun <KEY, VALUE> createPersistentStorage(
     icContext: IncrementalCompilationContext,
 ): PersistentStorage<KEY, VALUE> {
     return LazyStorage(storageFile, keyDescriptor, valueExternalizer).let { storage ->
-        if (icContext.keepIncrementalCompilationCachesInMemory) {
+        if (icContext.icFeatures.keepIncrementalCompilationCachesInMemory) {
             InMemoryStorage(storage).also {
                 icContext.transaction.registerInMemoryStorageWrapper(it)
             }
@@ -170,7 +170,7 @@ fun <KEY, E> createAppendablePersistentStorage(
     icContext: IncrementalCompilationContext,
 ): AppendablePersistentStorage<KEY, E> {
     return AppendableLazyStorage(storageFile, keyDescriptor, elementExternalizer).let { storage ->
-        if (icContext.keepIncrementalCompilationCachesInMemory) {
+        if (icContext.icFeatures.keepIncrementalCompilationCachesInMemory) {
             AppendableInMemoryStorage(storage).also {
                 icContext.transaction.registerInMemoryStorageWrapper(it)
             }