From 385b298f305ff84c15d1d7076adcc22b20777d88 Mon Sep 17 00:00:00 2001 From: Sarah Haggarty Date: Mon, 4 Nov 2024 13:49:14 +0100 Subject: [PATCH] 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.