Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document new compilerOptions DSL for 2.1.0 #4520

Open
wants to merge 2 commits into
base: 2-1-0-doc-update
Choose a base branch
from
+143 −131
Open

Document new compilerOptions DSL for 2.1.0 #4520

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c2a0838
chore: remove experimental status for compilerOptions DSL
sarahhaggarty Nov 4, 2024
385b298
update: add new KMP compiler options DSL
sarahhaggarty Nov 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 0 additions & 81 deletions docs/topics/multiplatform/multiplatform-configure-compilations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
}
}
}
}
```

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

```groovy
kotlin {
targets.all {
compilations.all {
compilerOptions.configure {
allWarningsAsErrors = true
}
}
}
}
```

</tab>
</tabs>

Alternatively, you can use the `compilerOptions {}` [top-level block](multiplatform-dsl-reference.md#top-level-blocks):

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

```kotlin
kotlin {
@OptIn(ExperimentalKotlinGradlePluginApi::class)
compilerOptions {
allWarningsAsErrors.set(true)
}
Expand All @@ -87,52 +51,14 @@ kotlin {
</tab>
</tabs>

> 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

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

```kotlin
kotlin {
jvm().compilations.all {
compilerOptions.configure {
jvmTarget.set(JvmTarget.JVM_1_8)
}
}
}
```

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

```groovy
kotlin {
jvm().compilations.all {
compilerOptions.configure {
jvmTarget = JvmTarget.JVM_1_8
}
}
}
```

</tab>
</tabs>

Alternatively, you can use the `compilerOptions {}` block at target level:

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

```kotlin
kotlin {
jvm {
@OptIn(ExperimentalKotlinGradlePluginApi::class)
compilerOptions {
jvmTarget.set(JvmTarget.JVM_1_8)
}
Expand All @@ -156,13 +82,6 @@ kotlin {
</tab>
</tabs>

> 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

<tabs group="build-script">
Expand Down
193 changes: 143 additions & 50 deletions docs/topics/multiplatform/multiplatform-dsl-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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** |
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| _&lt;targetName&gt;_ | 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** |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------|
| _&lt;targetName&gt;_ | 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 @@ -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

Expand Down Expand Up @@ -756,12 +744,8 @@ kotlin {
}

// Configure all compilations of all targets:
targets.all {
compilations.all {
compilerOptions.configure {
allWarningsAsErrors.set(true)
}
}
compilerOptions {
allWarningsAsErrors.set(true)
}
}
```
Expand All @@ -783,29 +767,47 @@ kotlin {
}

// Configure all compilations of all targets:
targets.all {
compilations.all {
compilerOptions.configure {
allWarningsAsErrors = true
}
}
compilerOptions {
allWarningsAsErrors = true
}
}
```

</tab>
</tabs>

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:

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

```kotlin
kotlin {

// Configure all compilations of all targets:
@OptIn(ExperimentalKotlinGradlePluginApi::class)
// Configures all compilations of all targets
compilerOptions {
allWarningsAsErrors.set(true)
}
Expand All @@ -817,8 +819,7 @@ kotlin {

```groovy
kotlin {

// Configure all compilations of all targets:
// Configures all compilations of all targets:
compilerOptions {
allWarningsAsErrors = true
}
Expand All @@ -828,12 +829,104 @@ kotlin {
</tab>
</tabs>

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

<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

Expand Down