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.
+
+{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.