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..e7617ac9155 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](#compiler-options) 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](#compiler-options) 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) } } ``` @@ -783,12 +767,8 @@ kotlin { } // Configure all compilations of all targets: - targets.all { - compilations.all { - compilerOptions.configure { - allWarningsAsErrors = true - } - } + compilerOptions { + allWarningsAsErrors = true } } ``` @@ -796,16 +776,38 @@ kotlin { -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): +## 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 { - - // Configure all compilations of all targets: - @OptIn(ExperimentalKotlinGradlePluginApi::class) + // Configures all compilations of all targets compilerOptions { allWarningsAsErrors.set(true) } @@ -817,8 +819,7 @@ kotlin { ```groovy kotlin { - - // Configure all compilations of all targets: + // Configures all compilations of all targets: compilerOptions { allWarningsAsErrors = true } @@ -828,12 +829,104 @@ 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"} +### 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