Skip to content

Commit b865124

Browse files
sarahhaggartysarahhaggarty
committed
update: add compilerOptions top-level block
1 parent 3515d48 commit b865124

File tree

3 files changed

+182
-33
lines changed

3 files changed

+182
-33
lines changed

‎docs/topics/multiplatform/multiplatform-configure-compilations.md

Lines changed: 99 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,11 @@ available for all or specific targets.
2424

2525
## Configure all compilations
2626

27+
This example configures a compiler option that is common across all targets:
28+
29+
<tabs group="build-script">
30+
<tab title="Kotlin" group-key="kotlin">
31+
2732
```kotlin
2833
kotlin {
2934
targets.all {
@@ -36,6 +41,58 @@ kotlin {
3641
}
3742
```
3843

44+
</tab>
45+
<tab title="Groovy" group-key="groovy">
46+
47+
```groovy
48+
kotlin {
49+
targets.all {
50+
compilations.all {
51+
compilerOptions.configure {
52+
allWarningsAsErrors = true
53+
}
54+
}
55+
}
56+
}
57+
```
58+
59+
</tab>
60+
</tabs>
61+
62+
Alternatively, you can use the `compilerOptions {}` [top-level block](multiplatform-dsl-reference.md#top-level-blocks):
63+
64+
<tabs group="build-script">
65+
<tab title="Kotlin" group-key="kotlin">
66+
67+
```kotlin
68+
kotlin {
69+
@OptIn(ExperimentalKotlinGradlePluginApi::class)
70+
compilerOptions {
71+
allWarningsAsErrors.set(true)
72+
}
73+
}
74+
```
75+
76+
</tab>
77+
<tab title="Groovy" group-key="groovy">
78+
79+
```groovy
80+
kotlin {
81+
compilerOptions {
82+
allWarningsAsErrors = true
83+
}
84+
}
85+
```
86+
87+
</tab>
88+
</tabs>
89+
90+
> The support for `compilerOptions {}` as a top-level block is [Experimental](components-stability.md#stability-levels-explained)
91+
> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate
92+
> your feedback on it in [YouTrack](https://kotl.in/issue).
93+
>
94+
{type="warning"}
95+
3996
## Configure compilations for one target
4097

4198
<tabs group="build-script">
@@ -58,15 +115,54 @@ kotlin {
58115
kotlin {
59116
jvm().compilations.all {
60117
compilerOptions.configure {
118+
jvmTarget = JvmTarget.JVM_1_8
119+
}
120+
}
121+
}
122+
```
123+
124+
</tab>
125+
</tabs>
126+
127+
Alternatively, you can use the `compilerOptions {}` block at target level:
128+
129+
<tabs group="build-script">
130+
<tab title="Kotlin" group-key="kotlin">
131+
132+
```kotlin
133+
kotlin {
134+
jvm {
135+
@OptIn(ExperimentalKotlinGradlePluginApi::class)
136+
compilerOptions {
61137
jvmTarget.set(JvmTarget.JVM_1_8)
62138
}
63139
}
64140
}
65141
```
66142

143+
</tab>
144+
<tab title="Groovy" group-key="groovy">
145+
146+
```groovy
147+
kotlin {
148+
jvm {
149+
compilerOptions {
150+
jvmTarget = JvmTarget.JVM_1_8
151+
}
152+
}
153+
}
154+
```
155+
67156
</tab>
68157
</tabs>
69158

159+
> The support for the `compilerOptions {}` block at target level is [Experimental](components-stability.md#stability-levels-explained)
160+
> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate
161+
> your feedback on it in [YouTrack](https://kotl.in/issue).
162+
>
163+
{type="warning"}
164+
165+
70166
## Configure one compilation
71167

72168
<tabs group="build-script">
@@ -92,7 +188,7 @@ kotlin {
92188
jvm {
93189
compilations.main {
94190
compilerOptions.configure {
95-
jvmTarget.set(JvmTarget.JVM_1_8)
191+
jvmTarget = JvmTarget.JVM_1_8
96192
}
97193
}
98194
}
@@ -277,7 +373,7 @@ kotlin {
277373
myInterop {
278374
// Def-file describing the native API.
279375
// The default path is src/nativeInterop/cinterop/<interop-name>.def
280-
definitionFile.set(project.file("def-file.def"))
376+
definitionFile = project.file("def-file.def")
281377
282378
// Package to place the Kotlin API generated.
283379
packageName 'org.sample'
@@ -320,7 +416,7 @@ The default source set `commonMain` is added to each production (application or
320416
The `commonTest` source set is similarly added to the compilations of unit test and instrumented test variants.
321417

322418
Annotation processing with [`kapt`](kapt.md) is also supported, but due to current limitations it requires that the Android target
323-
is created before the `kapt` dependencies are configured, which needs to be done in a top-level `dependencies` block rather
419+
is created before the `kapt` dependencies are configured, which needs to be done in a top-level `dependencies {}` block rather
324420
than within Kotlin source set dependencies.
325421

326422
```kotlin

‎docs/topics/multiplatform/multiplatform-dsl-reference.md

Lines changed: 81 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -33,15 +33,22 @@ plugins {
3333

3434
## Top-level blocks
3535

36-
`kotlin` is the top-level block for multiplatform project configuration in the Gradle build script.
37-
Inside `kotlin`, you can write the following blocks:
38-
39-
| **Block** | **Description** |
40-
|------------------|--------------------------------------------------------------------------------------------------------------------------|
41-
| _\<targetName\>_ | Declares a particular target of a project. The names of available targets are listed in the [Targets](#targets) section. |
42-
| `targets` | All targets of the project. |
43-
| `presets` | All predefined targets. Use this for [configuring multiple predefined targets](#targets) at once. |
44-
| `sourceSets` | Configures predefined and declares custom [source sets](#source-sets) of the project. |
36+
`kotlin {}` is the top-level block for multiplatform project configuration in the Gradle build script.
37+
Inside `kotlin {}`, you can write the following blocks:
38+
39+
| **Block** | **Description** |
40+
|-------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
41+
| _\<targetName\>_ | Declares a particular target of a project. The names of available targets are listed in the [Targets](#targets) section. |
42+
| `targets` | All targets of the project. |
43+
| `presets` | All predefined targets. Use this for [configuring multiple predefined targets](#targets) at once. |
44+
| `sourceSets` | Configures predefined and declares custom [source sets](#source-sets) of the project. |
45+
| `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)` |
46+
47+
> The support for `compilerOptions {}` as a top-level block is [Experimental](components-stability.md#stability-levels-explained)
48+
> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate
49+
> your feedback on it in [YouTrack](https://kotl.in/issue).
50+
>
51+
{type="warning"}
4552

4653
## Targets
4754

@@ -51,7 +58,7 @@ one of the supported platforms. Kotlin provides target presets for each platform
5158
Each target can have one or more [compilations](#compilations). In addition to default compilations for
5259
test and production purposes, you can [create custom compilations](multiplatform-configure-compilations.md#create-a-custom-compilation).
5360

54-
The targets of a multiplatform project are described in the corresponding blocks inside `kotlin`, for example, `jvm`, `android`, `iosArm64`.
61+
The targets of a multiplatform project are described in the corresponding blocks inside `kotlin {}`, for example, `jvm`, `android`, `iosArm64`.
5562
The complete list of available targets is the following:
5663

5764
<table>
@@ -118,13 +125,20 @@ Each target can have one or more [compilations](#compilations).
118125

119126
In any target block, you can use the following declarations:
120127

121-
| **Name** | **Description** |
122-
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------|
123-
| `attributes` | Attributes used for [disambiguating targets](multiplatform-set-up-targets.md#distinguish-several-targets-for-one-platform) for a single platform. |
124-
| `preset` | The preset that the target has been created from, if any. |
125-
| `platformType` | Designates the Kotlin platform of this target. Available values: `jvm`, `androidJvm`, `js`, `native`, `common`. |
126-
| `artifactsTaskName` | The name of the task that builds the resulting artifacts of this target. |
127-
| `components` | The components used to setup Gradle publications. |
128+
| **Name** | **Description** |
129+
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
130+
| `attributes` | Attributes used for [disambiguating targets](multiplatform-set-up-targets.md#distinguish-several-targets-for-one-platform) for a single platform. |
131+
| `preset` | The preset that the target has been created from, if any. |
132+
| `platformType` | Designates the Kotlin platform of this target. Available values: `jvm`, `androidJvm`, `js`, `native`, `common`. |
133+
| `artifactsTaskName` | The name of the task that builds the resulting artifacts of this target. |
134+
| `components` | The components used to setup Gradle publications. |
135+
| `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)` |
136+
137+
> The support for `compilerOptions {}` as a common target configuration is [Experimental](components-stability.md#stability-levels-explained)
138+
> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate
139+
> your feedback on it in [YouTrack](https://kotl.in/issue).
140+
>
141+
{type="warning"}
128142

129143
### JVM targets
130144

@@ -149,7 +163,7 @@ kotlin {
149163

150164
### JavaScript targets
151165

152-
The `js` block describes the configuration of JavaScript targets. It can contain one of two blocks depending on the target execution environment:
166+
The `js {}` block describes the configuration of JavaScript targets. It can contain one of two blocks depending on the target execution environment:
153167

154168
| **Name** | **Description** |
155169
|-----------|--------------------------------------|
@@ -160,7 +174,7 @@ Learn more about [configuring Kotlin/JS projects](js-project-setup.md).
160174

161175
#### Browser
162176

163-
`browser` can contain the following configuration blocks:
177+
`browser {}` can contain the following configuration blocks:
164178

165179
| **Name** | **Description** |
166180
|----------------|----------------------------------------------------------------------------|
@@ -187,7 +201,7 @@ kotlin {
187201

188202
#### Node.js
189203

190-
`nodejs` can contain configurations of test and run tasks:
204+
`nodejs {}` can contain configurations of test and run tasks:
191205

192206
| **Name** | **Description** |
193207
|------------|-----------------------------------|
@@ -382,7 +396,7 @@ kotlin {
382396
myInterop {
383397
// Def-file describing the native API.
384398
// The default path is src/nativeInterop/cinterop/<interop-name>.def
385-
definitionFile.set(project.file("def-file.def"))
399+
definitionFile = project.file("def-file.def")
386400
387401
// Package to place the Kotlin API generated.
388402
packageName 'org.sample'
@@ -434,7 +448,7 @@ Learn more about [compilation for Android](multiplatform-configure-compilations.
434448

435449
## Source sets
436450

437-
The `sourceSets` block describes source sets of the project. A source set contains Kotlin source files that participate
451+
The `sourceSets {}` block describes source sets of the project. A source set contains Kotlin source files that participate
438452
in compilations together, along with their resources, dependencies, and language settings.
439453

440454
A multiplatform project contains [predefined](#predefined-source-sets) source sets for its targets;
@@ -516,7 +530,7 @@ Note that a newly created source set isn't connected to other ones. To use it in
516530

517531
### Source set parameters
518532

519-
Configurations of source sets are stored inside the corresponding blocks of `sourceSets`. A source set has the following parameters:
533+
Configurations of source sets are stored inside the corresponding blocks of `sourceSets {}`. A source set has the following parameters:
520534

521535
| **Name** | **Description** |
522536
|--------------------|----------------------------------------------------------------------------------------|
@@ -727,7 +741,7 @@ kotlin {
727741
jvm {
728742
compilations.main.compilerOptions.configure {
729743
// Setup the Kotlin compiler options for the 'main' compilation:
730-
jvmTarget.set(JvmTarget.JVM_1_8)
744+
jvmTarget = JvmTarget.JVM_1_8
731745
}
732746
733747
compilations.main.compileKotlinTask // get the Kotlin task 'compileKotlinJvm'
@@ -739,7 +753,7 @@ kotlin {
739753
targets.all {
740754
compilations.all {
741755
compilerOptions.configure {
742-
allWarningsAsError.set(true)
756+
allWarningsAsErrors = true
743757
}
744758
}
745759
}
@@ -749,9 +763,48 @@ kotlin {
749763
</tab>
750764
</tabs>
751765

766+
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):
767+
768+
<tabs group="build-script">
769+
<tab title="Kotlin" group-key="kotlin">
770+
771+
```kotlin
772+
kotlin {
773+
774+
// Configure all compilations of all targets:
775+
@OptIn(ExperimentalKotlinGradlePluginApi::class)
776+
compilerOptions {
777+
allWarningsAsErrors.set(true)
778+
}
779+
}
780+
```
781+
782+
</tab>
783+
<tab title="Groovy" group-key="groovy">
784+
785+
```groovy
786+
kotlin {
787+
788+
// Configure all compilations of all targets:
789+
compilerOptions {
790+
allWarningsAsErrors = true
791+
}
792+
}
793+
```
794+
795+
</tab>
796+
</tabs>
797+
798+
> The support for `compilerOptions {}` as a top-level block is [Experimental](components-stability.md#stability-levels-explained)
799+
> and requires opt-in. It may be dropped or changed at any time. Use it only for evaluation purposes. We would appreciate
800+
> your feedback on it in [YouTrack](https://kotl.in/issue).
801+
>
802+
{type="warning"}
803+
804+
752805
## Dependencies
753806

754-
The `dependencies` block of the source set declaration contains the dependencies of this source set.
807+
The `dependencies {}` block of the source set declaration contains the dependencies of this source set.
755808

756809
Learn more about [configuring dependencies](gradle-configure-project.md).
757810

@@ -810,7 +863,7 @@ kotlin {
810863
Additionally, source sets can depend on each other and form a hierarchy.
811864
In this case, the [`dependsOn()`](#source-set-parameters) relation is used.
812865

813-
Source set dependencies can also be declared in the top-level `dependencies` block of the build script.
866+
Source set dependencies can also be declared in the top-level `dependencies {}` block of the build script.
814867
In this case, their declarations follow the pattern `<sourceSetName><DependencyKind>`, for example, `commonMainApi`.
815868

816869
<tabs group="build-script">
@@ -838,7 +891,7 @@ dependencies {
838891

839892
## Language settings
840893

841-
The `languageSettings` block of a source set defines certain aspects of project analysis and build. The following language settings are available:
894+
The `languageSettings {}` block of a source set defines certain aspects of project analysis and build. The following language settings are available:
842895

843896
| **Name** | **Description** |
844897
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

‎docs/topics/multiplatform/multiplatform-ios-dependencies.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,7 @@ and [frameworks](#add-a-framework-without-cocoapods), but the idea remains the s
141141
cinterops {
142142
DateTools {
143143
// Path to the .def file
144-
definitionFile.set(project.file("src/nativeInterop/cinterop/DateTools.def"))
144+
definitionFile = project.file("src/nativeInterop/cinterop/DateTools.def")
145145

146146
// Directories for header search (an analogue of the -I<path> compiler option)
147147
includeDirs("include/this/directory", "path/to/another/directory")
@@ -232,7 +232,7 @@ import DateTools.*
232232
cinterops {
233233
DateTools {
234234
// Path to the .def file
235-
definitionFile.set(project.file("src/nativeInterop/cinterop/MyFramework.def"))
235+
definitionFile = project.file("src/nativeInterop/cinterop/MyFramework.def")
236236
237237
compilerOpts("-framework", "MyFramework", "-F/path/to/framework/")
238238
}

0 commit comments

Comments
 (0)