From 020ad64b3c49203e70a3ebea26483c0e92337051 Mon Sep 17 00:00:00 2001 From: Yahor Berdnikau Date: Wed, 19 Jul 2023 23:15:58 +0200 Subject: [PATCH] [Gradle] Update documentation for Kotlin tasks ^KT-58858 In Progress --- .../kotlin/gradle/tasks/KotlinTaskConfigs.kt | 197 ++++++++++++++++-- .../kotlin/gradle/tasks/KotlinToolTask.kt | 4 +- 2 files changed, 178 insertions(+), 23 deletions(-) diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinTaskConfigs.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinTaskConfigs.kt index 955529b84b4..fd4be7d5b70 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinTaskConfigs.kt +++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinTaskConfigs.kt @@ -19,7 +19,14 @@ import org.jetbrains.kotlin.gradle.dsl.* import org.jetbrains.kotlin.gradle.dsl.jvm.JvmTargetValidationMode import org.jetbrains.kotlin.gradle.plugin.CompilerPluginConfig +/** + * Represents a Kotlin task participating in some stage of the build by compiling sources or running additional Kotlin tools. + */ interface KotlinCompileTool : PatternFilterable, Task { + + /** + * The configured task inputs (for example, Kotlin sources) which are used to produce a task artifact. + */ @get:InputFiles @get:SkipWhenEmpty @get:IgnoreEmptyDirectories @@ -28,21 +35,35 @@ interface KotlinCompileTool : PatternFilterable, Task { val sources: FileCollection /** - * Sets sources for this task. - * The given sources object is evaluated as per [org.gradle.api.Project.files]. + * Adds input sources for this task. + * + * @param sources object is evaluated as per [org.gradle.api.Project.files]. */ fun source(vararg sources: Any) /** - * Sets sources for this task. - * The given sources object is evaluated as per [org.gradle.api.Project.files]. + * Sets input sources for this task. + * + * **Note**: due to [a bug](https://youtrack.jetbrains.com/issue/KT-59632/KotlinCompileTool.setSource-should-replace-existing-sources), + * the `setSource()` function does not update already added sources. + * + * @param sources object is evaluated as per [org.gradle.api.Project.files]. */ fun setSource(vararg sources: Any) + /** + * Collection of external artifacts participating in the output artifact generation. + * + * For example, a Kotlin/JVM compilation task has external JAR files or an + * external location with already compiled class files. + */ @get:Classpath @get:Incremental val libraries: ConfigurableFileCollection + /** + * The destination directory where the task artifact can be found. + */ @get:OutputDirectory val destinationDirectory: DirectoryProperty @@ -53,36 +74,68 @@ interface KotlinCompileTool : PatternFilterable, Task { override fun getIncludes(): MutableSet } +/** + * Represents any Kotlin compilation task including common task inputs. + */ interface BaseKotlinCompile : KotlinCompileTool { + /** + * Paths to the output directories of the friend modules whose internal declarations should be visible. + */ @get:Internal val friendPaths: ConfigurableFileCollection + /** + * Kotlin compiler plugins artifacts + * , such as JAR or class files, that participate in the compilation process. All files that are permitted in the [JVM classpath](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html) are permitted here. + */ @get:Classpath val pluginClasspath: ConfigurableFileCollection + /** + * The configuration for the Kotlin compiler plugin added in [pluginClasspath] using [CompilerPluginConfig]. + */ + @get:Nested + val pluginOptions: ListProperty + + // Exists only to be used in 'KotlinCompileCommon' task. + // Should be removed once 'moduleName' will be moved into CommonCompilerArguments + /** + * @suppress + */ @get:Input val moduleName: Property + /** + * Specifies the name of [org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet] that is compiled. + */ @get:Internal val sourceSetName: Property + /** + * Enables the [Kotlin Multiplatform](https://kotlinlang.org/docs/multiplatform-mobile-getting-started.html) flag for compilation. + */ @get:Input val multiPlatformEnabled: Property + /** + * Enable more granular tracking of inter-modules as part of incremental compilation. Useful in Android projects. + */ @get:Input val useModuleDetection: Property - - @get:Nested - val pluginOptions: ListProperty } -@Suppress("TYPEALIAS_EXPANSION_DEPRECATION") +/** + * Represents a Kotlin task compiling given Kotlin sources into JVM class files. + */ interface KotlinJvmCompile : BaseKotlinCompile, KotlinCompileDeprecated, KotlinCompilationTask, UsesKotlinJavaToolchain { + /** + * @suppress + */ @get:Deprecated( message = "Please migrate to compilerOptions.moduleName", replaceWith = ReplaceWith("compilerOptions.moduleName") @@ -91,6 +144,9 @@ interface KotlinJvmCompile : BaseKotlinCompile, @get:Input override val moduleName: Property + /** + * @suppress + */ // JVM specific @get:Internal("Takes part in compiler args.") @Deprecated( @@ -102,18 +158,18 @@ interface KotlinJvmCompile : BaseKotlinCompile, /** * Controls JVM target validation mode between this task and the Java compilation task from Gradle for the same source set. * - * The same JVM targets ensure that the produced jar file contains class files of the same JVM bytecode version, - * which is important to avoid compatibility issues for the code consumers. + * Using the same JVM targets ensures that the produced JAR file contains class files of the same JVM bytecode version, + * which is important to avoid compatibility issues for users of your code. * - * Also, Gradle Java compilation task [org.gradle.api.tasks.compile.JavaCompile.targetCompatibility] controls value - * of "org.gradle.jvm.version" [attribute](https://docs.gradle.org/current/javadoc/org/gradle/api/attributes/java/TargetJvmVersion.html) - * which itself controls the produced artifact minimal supported JVM version via + * The Gradle Java compilation task [org.gradle.api.tasks.compile.JavaCompile.targetCompatibility] controls the value + * of the `org.gradle.jvm.version` [attribute](https://docs.gradle.org/current/javadoc/org/gradle/api/attributes/java/TargetJvmVersion.html) + * which itself controls the produced artifact's minimum supported JVM version via * [Gradle Module Metadata](https://docs.gradle.org/current/userguide/publishing_gradle_module_metadata.html). - * This allows Gradle to check compatibility of dependencies at dependency resolution time. + * This allows Gradle to check the compatibility of dependencies at dependency resolution time. * - * To avoid problems with different targets we advise to use [JDK Toolchain](https://kotl.in/gradle/jvm/toolchain) feature. + * To avoid problems with different targets, we advise using the [JVM Toolchain](https://kotl.in/gradle/jvm/toolchain) feature. * - * Default value for builds with Gradle <8.0 is [JvmTargetValidationMode.WARNING], + * The default value for builds with Gradle <8.0 is [JvmTargetValidationMode.WARNING], * while for builds with Gradle 8.0+ it is [JvmTargetValidationMode.ERROR]. * * @since 1.9.0 @@ -122,13 +178,35 @@ interface KotlinJvmCompile : BaseKotlinCompile, val jvmTargetValidationMode: Property } +/** + * Represents a Kotlin task that generates stubs from Java annotation processing results. + * + * This task generates annotation processing output stubs (without the actual method implementations) + * using Java source code. + * These generated stubs can be referenced in Kotlin source code compilation before completing + * annotation processing. + * + * This task is a part of [Kotlin/Kapt](https://kotlinlang.org/docs/kapt.html). + */ interface KaptGenerateStubs : KotlinJvmCompile { + /** + * The directory where generated stubs can be found. + */ @get:OutputDirectory val stubsDir: DirectoryProperty + /** + * Allows adding artifacts (accepted by [JVM classpath](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/classpath.html)) + * containing implementation of Java [annotation processor](https://jcp.org/en/jsr/detail?id=269). + * + * Configure this property with the same artifacts as its related [Kapt] task. + */ @get:Internal("Not an input, just passed as kapt args. ") val kaptClasspath: ConfigurableFileCollection + /** + * @suppress + */ @get:Deprecated( message = "Please migrate to compilerOptions.moduleName", replaceWith = ReplaceWith("compilerOptions.moduleName") @@ -138,52 +216,102 @@ interface KaptGenerateStubs : KotlinJvmCompile { override val moduleName: Property } +/** + * Represents a Kotlin task that runs annotation processing using [Kotlin/Kapt](https://kotlinlang.org/docs/kapt.html). + * + * **Note:** Always run this task after its related [KaptGenerateStubs] and [KotlinJvmCompile] tasks. + */ interface BaseKapt : Task, UsesKotlinJavaToolchain { - //part of kaptClasspath consisting from external artifacts only - //basically kaptClasspath = kaptExternalClasspath + artifacts built locally + // part of kaptClasspath consisting from external artifacts only + // basically kaptClasspath = kaptExternalClasspath + artifacts built locally + // TODO (Yahor): should not be a part of public api + /** + * @suppress + */ @get:Classpath val kaptExternalClasspath: ConfigurableFileCollection + /** + * The names of Gradle's [org.gradle.api.artifacts.Configuration] that contains all the annotation processor artifacts + * used to configure [kaptClasspath]. + */ @get:Internal val kaptClasspathConfigurationNames: ListProperty /** - * Output directory that contains caches necessary to support incremental annotation processing. + * The output directory containing the caches necessary to support incremental annotation processing. */ @get:LocalState val incAptCache: DirectoryProperty + /** + * The directory where class files generated by annotation processing can be found. + */ @get:OutputDirectory val classesDir: DirectoryProperty + /** + * The directory where Java source files generated by annotation processing can be found. + */ @get:OutputDirectory val destinationDir: DirectoryProperty - /** Used in the model builder only. */ + // Used in the model builder only + /** + * The directory where Java source files generated by annotation processing can be found. + */ @get:OutputDirectory val kotlinSourcesDestinationDir: DirectoryProperty + /** + * Represents a list of annotation processor option providers. + * + * Accepts a [List] of [org.gradle.process.CommandLineArgumentProvider]s. + */ @get:Nested val annotationProcessorOptionProviders: MutableList + /** + * The directory where the generated related [KaptGenerateStubs] task stub can be found. + */ @get:Internal val stubsDir: DirectoryProperty + /** + * Allows adding artifacts (usually JAR files) + * that contain the implementation of the Java [annotation processor](https://jcp.org/en/jsr/detail?id=269). + * + * Should be configured with the same artifacts as in the related [KaptGenerateStubs] task. + */ @get:Classpath val kaptClasspath: ConfigurableFileCollection + /** + * The directory that contains the compiled related [KotlinJvmCompile] task classes. + */ @get:Internal val compiledSources: ConfigurableFileCollection + /** + * Contains all artifacts from the related [KotlinJvmCompile.libraries] task input. + */ @get:Internal("Task implementation adds correct input annotation.") val classpath: ConfigurableFileCollection - /** Needed for the model builder. */ + // Needed for the model builder + /** + * Specifies the name of [org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet] for which task is + * doing annotation processing. + */ @get:Internal val sourceSetName: Property + /** + * Contains all Java source code used in this compilation + * and generated by related [KaptGenerateStubs] task stubs. + */ @get:InputFiles @get:IgnoreEmptyDirectories @get:Incremental @@ -191,18 +319,45 @@ interface BaseKapt : Task, @get:PathSensitive(PathSensitivity.RELATIVE) val source: ConfigurableFileCollection + /** + * Enable searching for annotation processors in the [classpath]. + */ @get:Input val includeCompileClasspath: Property + /** + * Java source compatibility in the form of the Java language level for the produced class files and Java source code. + * + * Check the `javac` `-source` command line option + * [description](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.html#options) + * for the possible values for the Java language level. + * + * @see [org.gradle.api.tasks.compile.AbstractCompile.setSourceCompatibility] + */ @get:Internal("Used to compute javac option.") val defaultJavaSourceCompatibility: Property } +/** + * Represents a [BaseKapt] task whose implementation is running [Kotlin/Kapt](https://kotlinlang.org/docs/kapt.html) + * directly (without using the Kotlin compiler). + */ interface Kapt : BaseKapt { + /** + * Add JDK classes to the [BaseKapt.classpath]. + * + * For example, in Android projects this should be disabled. + */ @get:Input val addJdkClassesToClasspath: Property + /** + * The file collection that contains `org.jetbrains.kotlin:kotlin-annotation-processing-gradle` and `kotlin-stdlib` + * artifacts that are used to run annotation processing. + * + * The artifacts' versions must be the same as the version of the Kotlin compiler used to compile the related Kotlin sources. + */ @get:Classpath val kaptJars: ConfigurableFileCollection } \ No newline at end of file diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinToolTask.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinToolTask.kt index d2b1db0c303..2e82290f48f 100644 --- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinToolTask.kt +++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/tasks/KotlinToolTask.kt @@ -13,8 +13,8 @@ import org.jetbrains.kotlin.gradle.dsl.KotlinCommonCompilerToolOptions /** * Represents a Kotlin task performing further processing of compiled code via additional Kotlin tools using configurable [toolOptions]. * - * Check [KotlinCommonCompilerToolOptions] inheritors (excluding [KotlinCommonCompilerToolOptions]) for possible available for configuration - * tool options. + * Check [KotlinCommonCompilerToolOptions] inheritors (excluding [KotlinCommonCompilerToolOptions]) for the possible configuration + * options. * * @see [KotlinCommonCompilerToolOptions] */