Skip to content

Commit

Permalink
update: add new KMP compiler options DSL
Browse files Browse the repository at this point in the history
  • Loading branch information
@sarahhaggarty
sarahhaggarty committed Nov 4, 2024
1 parent c2a0838 commit 385b298
Showing 1 changed file with 167 additions and 15 deletions.
182 changes: 167 additions & 15 deletions docs/topics/multiplatform/multiplatform-dsl-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -776,6 +776,158 @@ kotlin {
</tab>
</tabs>

## 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:

<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

```kotlin
kotlin {
// Configures all compilations of all targets
compilerOptions {
allWarningsAsErrors.set(true)
}
}
```

</tab>
<tab title="Groovy" group-key="groovy">

```groovy
kotlin {
// Configures all compilations of all targets:
compilerOptions {
allWarningsAsErrors = true
}
}
```

</tab>
</tabs>

### Target level

To configure compiler options for a specific target in your project, use the `compilerOptions {}` block inside the target block:

<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

```kotlin
kotlin {
jvm {
// Configures all compilations of the JVM target
compilerOptions {
allWarningsAsErrors.set(true)
}
}
}
```

</tab>
<tab title="Groovy" group-key="groovy">

```groovy
kotlin {
jvm {
// Configures all compilations of the JVM target
compilerOptions {
allWarningsAsErrors = true
}
}
}
```

</tab>
</tabs>

### Compilation unit level

To configure compiler options for a specific compilation, use the `compilerOptions {}` block inside the `compilations` object:

<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

```kotlin
kotlin {
jvm {
val main by compilations.getting {
compilerOptions.configure {
// Configures the 'main' compilation:
allWarningsAsErrors.set(true)
}
}
}
}
```

</tab>
<tab title="Groovy" group-key="groovy">

```groovy
kotlin {
jvm {
compilations.main.compilerOptions.configure {
// Configures the 'main' compilation:
allWarningsAsErrors = true
}
}
}
```

</tab>
</tabs>

To configure compiler options for a specific task, use the `compilerOptions {}` block inside the task:

<tabs group="build-script">
<tab title="Kotlin" group-key="kotlin">

```kotlin
task.named<KotlinJvmCompile>("compileKotlinJvm"){
compilerOptions {
allWarningsAsErrors.set(true)
}
}
```

</tab>
<tab title="Groovy" group-key="groovy">

```groovy
task.named<KotlinJvmCompile>("compileKotlinJvm"){
compilerOptions {
allWarningsAsErrors = true
}
}
```

</tab>
</tabs>

## Dependencies

The `dependencies {}` block of the source set declaration contains the dependencies of this source set.
Expand Down

0 comments on commit 385b298

Please sign in to comment.