From c2a0838b745c3bd2735e9d910cc34667a3934ab9 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Mon, 4 Nov 2024 12:04:24 +0100 Subject: [PATCH 1/2] chore: remove experimental status for compilerOptions DSL --- .../multiplatform-configure-compilations.md | 81 ---------------- .../multiplatform-dsl-reference.md | 93 ++++--------------- 2 files changed, 17 insertions(+), 157 deletions(-) diff --git a/docs/topics/multiplatform/multiplatform-configure-compilations.md b/docs/topics/multiplatform/multiplatform-configure-compilations.md index 764f90f8d98..dfe57fceb9d 100644 --- a/docs/topics/multiplatform/multiplatform-configure-compilations.md +++ b/docs/topics/multiplatform/multiplatform-configure-compilations.md @@ -31,42 +31,6 @@ This example configures a compiler option that is common across all targets: ```kotlin kotlin { - targets.all { - compilations.all { - compilerOptions.configure { - allWarningsAsErrors.set(true) - } - } - } -} -``` - - - - -```groovy -kotlin { - targets.all { - compilations.all { - compilerOptions.configure { - allWarningsAsErrors = true - } - } - } -} -``` - - - - -Alternatively, you can use the `compilerOptions {}` [top-level block](multiplatform-dsl-reference.md#top-level-blocks): - - - - -```kotlin -kotlin { - @OptIn(ExperimentalKotlinGradlePluginApi::class) compilerOptions { allWarningsAsErrors.set(true) } @@ -87,52 +51,14 @@ kotlin { -> The support for `compilerOptions {}` as a top-level block is [Experimental](components-stability.md#stability-levels-explained) -> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate -> your feedback on it in [YouTrack](https://kotl.in/issue). -> -{style="warning"} - ## Configure compilations for one target -```kotlin -kotlin { - jvm().compilations.all { - compilerOptions.configure { - jvmTarget.set(JvmTarget.JVM_1_8) - } - } -} -``` - - - - -```groovy -kotlin { - jvm().compilations.all { - compilerOptions.configure { - jvmTarget = JvmTarget.JVM_1_8 - } - } -} -``` - - - - -Alternatively, you can use the `compilerOptions {}` block at target level: - - - - ```kotlin kotlin { jvm { - @OptIn(ExperimentalKotlinGradlePluginApi::class) compilerOptions { jvmTarget.set(JvmTarget.JVM_1_8) } @@ -156,13 +82,6 @@ kotlin { -> The support for the `compilerOptions {}` block at target level is [Experimental](components-stability.md#stability-levels-explained) -> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate -> your feedback on it in [YouTrack](https://kotl.in/issue). -> -{style="warning"} - - ## Configure one compilation diff --git a/docs/topics/multiplatform/multiplatform-dsl-reference.md b/docs/topics/multiplatform/multiplatform-dsl-reference.md index 9320d43e89e..9ff3a0067a0 100644 --- a/docs/topics/multiplatform/multiplatform-dsl-reference.md +++ b/docs/topics/multiplatform/multiplatform-dsl-reference.md @@ -36,19 +36,13 @@ plugins { `kotlin {}` is the top-level block for multiplatform project configuration in the Gradle build script. Inside `kotlin {}`, you can write the following blocks: -| **Block** | **Description** | -|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| _<targetName>_ | Declares a particular target of a project. The names of available targets are listed in the [Targets](#targets) section. | -| `targets` | All targets of the project. | -| `presets` | All predefined targets. Use this for [configuring multiple predefined targets](#targets) at once. | -| `sourceSets` | Configures predefined and declares custom [source sets](#source-sets) of the project. | -| `compilerOptions` | Extension-level common [compiler options](gradle-compiler-options.md) that are used as defaults for all targets and shared source sets. To use it, add the following opt-in: `@OptIn(ExperimentalKotlinGradlePluginApi::class)` | - -> The support for `compilerOptions {}` as a top-level block is [Experimental](components-stability.md#stability-levels-explained) -> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate -> your feedback on it in [YouTrack](https://kotl.in/issue). -> -{style="warning"} +| **Block** | **Description** | +|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| _<targetName>_ | Declares a particular target of a project. The names of available targets are listed in the [Targets](#targets) section. | +| `targets` | All targets of the project. | +| `presets` | All predefined targets. Use this for [configuring multiple predefined targets](#targets) at once. | +| `sourceSets` | Configures predefined and declares custom [source sets](#source-sets) of the project. | +| `compilerOptions` | Extension-level common [compiler options](gradle-compiler-options.md) that are used as defaults for all targets and shared source sets. | ## Targets @@ -134,20 +128,14 @@ Each target can have one or more [compilations](#compilations). In any target block, you can use the following declarations: -| **Name** | **Description** | -|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `attributes` | Attributes used for [disambiguating targets](multiplatform-set-up-targets.md#distinguish-several-targets-for-one-platform) for a single platform. | -| `preset` | The preset that the target has been created from, if any. | -| `platformType` | Designates the Kotlin platform of this target. Available values: `jvm`, `androidJvm`, `js`, `wasm`, `native`, `common`. | -| `artifactsTaskName` | The name of the task that builds the resulting artifacts of this target. | -| `components` | The components used to setup Gradle publications. | -| `compilerOptions` | The [compiler options](gradle-compiler-options.md) used for the target. This declaration overrides any `compilerOptions {}` configured at [top level](multiplatform-dsl-reference.md#top-level-blocks). To use it, add the following opt-in: `@OptIn(ExperimentalKotlinGradlePluginApi::class)` | - -> The support for `compilerOptions {}` as a common target configuration is [Experimental](components-stability.md#stability-levels-explained) -> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate -> your feedback on it in [YouTrack](https://kotl.in/issue). -> -{style="warning"} +| **Name** | **Description** | +|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `attributes` | Attributes used for [disambiguating targets](multiplatform-set-up-targets.md#distinguish-several-targets-for-one-platform) for a single platform. | +| `preset` | The preset that the target has been created from, if any. | +| `platformType` | Designates the Kotlin platform of this target. Available values: `jvm`, `androidJvm`, `js`, `wasm`, `native`, `common`. | +| `artifactsTaskName` | The name of the task that builds the resulting artifacts of this target. | +| `components` | The components used to setup Gradle publications. | +| `compilerOptions` | The [compiler options](gradle-compiler-options.md) used for the target. This declaration overrides any `compilerOptions {}` configured at [top level](multiplatform-dsl-reference.md#top-level-blocks). | ### JVM targets @@ -756,12 +744,8 @@ kotlin { } // Configure all compilations of all targets: - targets.all { - compilations.all { - compilerOptions.configure { - allWarningsAsErrors.set(true) - } - } + compilerOptions { + allWarningsAsErrors.set(true) } } ``` @@ -782,42 +766,6 @@ kotlin { compilations.test.runtimeDependencyFiles // get the test runtime classpath } - // Configure all compilations of all targets: - targets.all { - compilations.all { - compilerOptions.configure { - allWarningsAsErrors = true - } - } - } -} -``` - - - - -Alternatively, to configure compiler options that are common for all targets, you can use the `compilerOptions {}` [top-level block](multiplatform-dsl-reference.md#top-level-blocks): - - - - -```kotlin -kotlin { - - // Configure all compilations of all targets: - @OptIn(ExperimentalKotlinGradlePluginApi::class) - compilerOptions { - allWarningsAsErrors.set(true) - } -} -``` - - - - -```groovy -kotlin { - // Configure all compilations of all targets: compilerOptions { allWarningsAsErrors = true @@ -828,13 +776,6 @@ kotlin { -> The support for `compilerOptions {}` as a top-level block is [Experimental](components-stability.md#stability-levels-explained) -> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate -> your feedback on it in [YouTrack](https://kotl.in/issue). -> -{style="warning"} - - ## Dependencies The `dependencies {}` block of the source set declaration contains the dependencies of this source set. From 385b298f305ff84c15d1d7076adcc22b20777d88 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Mon, 4 Nov 2024 13:49:14 +0100 Subject: [PATCH 2/2] update: add new KMP compiler options DSL --- .../multiplatform-dsl-reference.md | 182 ++++++++++++++++-- 1 file changed, 167 insertions(+), 15 deletions(-) diff --git a/docs/topics/multiplatform/multiplatform-dsl-reference.md b/docs/topics/multiplatform/multiplatform-dsl-reference.md index 9ff3a0067a0..e7617ac9155 100644 --- a/docs/topics/multiplatform/multiplatform-dsl-reference.md +++ b/docs/topics/multiplatform/multiplatform-dsl-reference.md @@ -36,13 +36,13 @@ plugins { `kotlin {}` is the top-level block for multiplatform project configuration in the Gradle build script. Inside `kotlin {}`, you can write the following blocks: -| **Block** | **Description** | -|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -| _<targetName>_ | Declares a particular target of a project. The names of available targets are listed in the [Targets](#targets) section. | -| `targets` | All targets of the project. | -| `presets` | All predefined targets. Use this for [configuring multiple predefined targets](#targets) at once. | -| `sourceSets` | Configures predefined and declares custom [source sets](#source-sets) of the project. | -| `compilerOptions` | Extension-level common [compiler options](gradle-compiler-options.md) that are used as defaults for all targets and shared source sets. | +| **Block** | **Description** | +|----------------------|--------------------------------------------------------------------------------------------------------------------------------| +| _<targetName>_ | Declares a particular target of a project. The names of available targets are listed in the [Targets](#targets) section. | +| `targets` | All targets of the project. | +| `presets` | All predefined targets. Use this for [configuring multiple predefined targets](#targets) at once. | +| `sourceSets` | Configures predefined and declares custom [source sets](#source-sets) of the project. | +| `compilerOptions` | Extension-level common [compiler options](#compiler-options) that are used as defaults for all targets and shared source sets. | ## Targets @@ -128,14 +128,14 @@ Each target can have one or more [compilations](#compilations). In any target block, you can use the following declarations: -| **Name** | **Description** | -|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `attributes` | Attributes used for [disambiguating targets](multiplatform-set-up-targets.md#distinguish-several-targets-for-one-platform) for a single platform. | -| `preset` | The preset that the target has been created from, if any. | -| `platformType` | Designates the Kotlin platform of this target. Available values: `jvm`, `androidJvm`, `js`, `wasm`, `native`, `common`. | -| `artifactsTaskName` | The name of the task that builds the resulting artifacts of this target. | -| `components` | The components used to setup Gradle publications. | -| `compilerOptions` | The [compiler options](gradle-compiler-options.md) used for the target. This declaration overrides any `compilerOptions {}` configured at [top level](multiplatform-dsl-reference.md#top-level-blocks). | +| **Name** | **Description** | +|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `attributes` | Attributes used for [disambiguating targets](multiplatform-set-up-targets.md#distinguish-several-targets-for-one-platform) for a single platform. | +| `preset` | The preset that the target has been created from, if any. | +| `platformType` | Designates the Kotlin platform of this target. Available values: `jvm`, `androidJvm`, `js`, `wasm`, `native`, `common`. | +| `artifactsTaskName` | The name of the task that builds the resulting artifacts of this target. | +| `components` | The components used to setup Gradle publications. | +| `compilerOptions` | The [compiler options](#compiler-options) used for the target. This declaration overrides any `compilerOptions {}` configured at [top level](multiplatform-dsl-reference.md#top-level-blocks). | ### JVM targets @@ -776,6 +776,158 @@ kotlin { +## Compiler options + +You can configure compiler options in your projects at three different levels: + +* **Extension level**, by using it as a top-level block. +* **Target level**. +* **Compilation unit level**, usually a specific compilation task. + +![Kotlin compiler options levels](compiler-options-levels.svg){width=700} + +Settings at a higher level work as defaults for the level below: + +* Compiler options set at the extension level are the default for target-level options, including shared source sets like `commonMain`, `nativeMain`, and `commonTest`. +* Compiler options set at the target level are the default for options at the compilation unit (task) level, like `compileKotlinJvm` and `compileTestKotlinJvm` tasks. + +Configurations made at a lower level override similar settings at higher levels: + +* Task-level compiler options override similar settings at the target or extension level. +* Target-level compiler options override similar settings at the extension level. + +For the list of possible compiler options, see [All compiler options](gradle-compiler-options.md#all-compiler-options). + +### Extension level + +To configure compiler options for all targets in your project, use the `compilerOptions {}` block at the top level: + + + + +```kotlin +kotlin { + // Configures all compilations of all targets + compilerOptions { + allWarningsAsErrors.set(true) + } +} +``` + + + + +```groovy +kotlin { + // Configures all compilations of all targets: + compilerOptions { + allWarningsAsErrors = true + } +} +``` + + + + +### Target level + +To configure compiler options for a specific target in your project, use the `compilerOptions {}` block inside the target block: + + + + +```kotlin +kotlin { + jvm { + // Configures all compilations of the JVM target + compilerOptions { + allWarningsAsErrors.set(true) + } + } +} +``` + + + + +```groovy +kotlin { + jvm { + // Configures all compilations of the JVM target + compilerOptions { + allWarningsAsErrors = true + } + } +} +``` + + + + +### Compilation unit level + +To configure compiler options for a specific compilation, use the `compilerOptions {}` block inside the `compilations` object: + + + + +```kotlin +kotlin { + jvm { + val main by compilations.getting { + compilerOptions.configure { + // Configures the 'main' compilation: + allWarningsAsErrors.set(true) + } + } + } +} +``` + + + + +```groovy +kotlin { + jvm { + compilations.main.compilerOptions.configure { + // Configures the 'main' compilation: + allWarningsAsErrors = true + } + } +} +``` + + + + +To configure compiler options for a specific task, use the `compilerOptions {}` block inside the task: + + + + +```kotlin +task.named("compileKotlinJvm"){ + compilerOptions { + allWarningsAsErrors.set(true) + } +} +``` + + + + +```groovy +task.named("compileKotlinJvm"){ + compilerOptions { + allWarningsAsErrors = true + } +} +``` + + + + ## Dependencies The `dependencies {}` block of the source set declaration contains the dependencies of this source set.