0
# Compilation Tasks
1

2
This document covers the Gradle tasks responsible for compiling Kotlin code across different platforms.
3

4
## Core Compilation Tasks
5

6
### KotlinCompile
7

8
The main JVM compilation task.
9

10
```kotlin { .api }
11
abstract class KotlinCompile : AbstractCompile(), KotlinCompilationTask<KotlinJvmCompilerOptions> {
12
    abstract override val compilerOptions: KotlinJvmCompilerOptions
13
    abstract val destinationDirectory: DirectoryProperty
14
    abstract val classpath: ConfigurableFileCollection
15
    abstract val libraries: ConfigurableFileCollection
16
    abstract val source: ConfigurableFileTree
17
    
18
    // Incremental compilation support
19
    abstract val incrementalProps: Property<IncrementalCompilationSpec>
20
    abstract val usePreciseJavaTracking: Property<Boolean>
21
}
22
```
23

24
**Usage Example:**
25

26
```kotlin
27
tasks.withType<KotlinCompile>().configureEach {
28
    compilerOptions {
29
        jvmTarget.set(JvmTarget.JVM_11)
30
        freeCompilerArgs.add("-Xjsr305=strict")
31
    }
32
}
33

34
// Configure specific compilation task
35
tasks.named<KotlinCompile>("compileKotlin") {
36
    destinationDirectory.set(layout.buildDirectory.dir("classes/kotlin/main"))
37
}
38
```
39

40
### AbstractKotlinCompile
41

42
Base class for all Kotlin compilation tasks.
43

44
```kotlin { .api }
45
abstract class AbstractKotlinCompile<T : KotlinCommonCompilerOptions> : AbstractCompile(), KotlinCompilationTask<T> {
46
    abstract override val compilerOptions: T
47
    abstract val kotlinSourceDirectories: ConfigurableFileCollection
48
    abstract val commonSourceSet: ConfigurableFileCollection
49
    abstract val moduleName: Property<String>
50
    
51
    // Compiler execution
52
    fun execute()
53
    
54
    // Source file handling
55
    fun getFilteredKotlinSources(): List<File>
56
}
57
```
58

59
### Kotlin2JsCompile
60

61
JavaScript compilation task.
62

63
```kotlin { .api }
64
abstract class Kotlin2JsCompile : AbstractKotlinCompile<KotlinJsCompilerOptions> {
65
    abstract val outputFileProperty: RegularFileProperty
66
    abstract val optionalOutputFile: RegularFileProperty
67
    abstract val kotlinJsModuleKind: Property<KotlinJsModuleKind>
68
    
69
    // JS-specific properties
70
    abstract val enhancedIncrementalSupport: Property<Boolean>
71
    abstract val sourceMapEmbedSources: Property<SourceMapEmbedSources>
72
}
73
```
74

75
**Usage Example:**
76

77
```kotlin
78
tasks.withType<Kotlin2JsCompile>().configureEach {
79
    compilerOptions {
80
        target.set("es2015")
81
        moduleKind.set(KotlinJsModuleKind.MODULE_ES)
82
        sourceMap.set(true)
83
    }
84
}
85
```
86

87
### KotlinCompileCommon
88

89
Common/metadata compilation task for multiplatform projects.
90

91
```kotlin { .api }
92
abstract class KotlinCompileCommon : AbstractKotlinCompile<KotlinMultiplatformCommonCompilerOptions> {
93
    abstract val expectActualLinker: Property<Boolean>
94
    abstract val refinesMetadata: ConfigurableFileCollection
95
}
96
```
97

98
## Native Compilation Tasks
99

100
### KotlinNativeCompile
101

102
Native compilation task.
103

104
```kotlin { .api }
105
abstract class KotlinNativeCompile : AbstractKotlinCompile<KotlinNativeCompilerOptions> {
106
    abstract val target: Property<String>
107
    abstract val debuggable: Property<Boolean>
108
    abstract val optimized: Property<Boolean>
109
    abstract val binaryOptions: MapProperty<String, String>
110
}
111
```
112

113
### KotlinNativeLink
114

115
Native linking task for creating final binaries.
116

117
```kotlin { .api }
118
abstract class KotlinNativeLink : DefaultTask() {
119
    abstract val binary: Property<NativeBinary>
120
    abstract val destinationDirectory: DirectoryProperty
121
    abstract val outputFile: RegularFileProperty
122
    abstract val linkerArgs: ListProperty<String>
123
    abstract val libraries: ConfigurableFileCollection
124
    abstract val exportLibraries: ConfigurableFileCollection
125
}
126
```
127

128
**Usage Example:**
129

130
```kotlin
131
tasks.withType<KotlinNativeLink>().configureEach {
132
    linkerArgs.addAll("-linker-option", "-L/usr/local/lib")
133
}
134
```
135

136
### KotlinNativeTest
137

138
Native test execution task.
139

140
```kotlin { .api }
141
abstract class KotlinNativeTest : AbstractTestTask() {
142
    abstract val executable: RegularFileProperty
143
    abstract val workingDir: DirectoryProperty
144
    abstract val args: ListProperty<String>
145
    abstract val environment: MapProperty<String, String>
146
}
147
```
148

149
## Task Configuration
150

151
### Kotlin Task Configuration DSL
152

153
```kotlin { .api }
154
// Configure all Kotlin compilation tasks
155
tasks.withType<KotlinCompile>().configureEach {
156
    compilerOptions {
157
        jvmTarget.set(JvmTarget.JVM_11)
158
        freeCompilerArgs.addAll(
159
            "-Xjsr305=strict",
160
            "-Xcontext-receivers"
161
        )
162
    }
163
}
164

165
// Configure JS compilation tasks
166
tasks.withType<Kotlin2JsCompile>().configureEach {
167
    compilerOptions {
168
        sourceMap.set(true)
169
        moduleKind.set(KotlinJsModuleKind.MODULE_COMMONJS)
170
    }
171
}
172

173
// Configure common/metadata compilation
174
tasks.withType<KotlinCompileCommon>().configureEach {
175
    compilerOptions {
176
        progressiveMode.set(true)
177
    }
178
}
179
```
180

181
### Incremental Compilation
182

183
```kotlin { .api }
184
interface IncrementalCompilationSpec {
185
    val enabled: Property<Boolean>
186
    val useClasspathSnapshot: Property<Boolean>
187
    val preciseJavaTracking: Property<Boolean>
188
}
189
```
190

191
**Configuration Example:**
192

193
```kotlin
194
tasks.withType<KotlinCompile>().configureEach {
195
    usePreciseJavaTracking.set(true)
196
    
197
    incrementalProps.set(
198
        objects.newInstance<IncrementalCompilationSpec>().apply {
199
            enabled.set(true)
200
            useClasspathSnapshot.set(true)
201
            preciseJavaTracking.set(true)
202
        }
203
    )
204
}
205
```
206

207
## Compiler Arguments and Options
208

209
### Free Compiler Arguments
210

211
Common compiler arguments that can be passed to any Kotlin compilation task.
212

213
```kotlin
214
compilerOptions {
215
    freeCompilerArgs.addAll(
216
        // Language features
217
        "-Xcontext-receivers",
218
        "-Xvalue-classes",
219
        
220
        // JVM-specific
221
        "-Xjsr305=strict",
222
        "-Xjvm-default=all",
223
        
224
        // Multiplatform
225
        "-Xexpect-actual-classes",
226
        
227
        // Experimental features
228
        "-opt-in=kotlinx.coroutines.ExperimentalCoroutinesApi",
229
        "-opt-in=kotlin.ExperimentalStdlibApi"
230
    )
231
}
232
```
233

234
### JVM Target Configuration
235

236
```kotlin { .api }
237
enum class JvmTarget(val description: String) {
238
    JVM_1_8("1.8"),
239
    JVM_9("9"),
240
    JVM_10("10"),
241
    JVM_11("11"),
242
    JVM_15("15"),
243
    JVM_17("17"),
244
    JVM_19("19"),
245
    JVM_20("20"),
246
    JVM_21("21")
247
}
248
```
249

250
### Module Kind for JavaScript
251

252
```kotlin { .api }
253
enum class KotlinJsModuleKind {
254
    MODULE_AMD,
255
    MODULE_COMMONJS,
256
    MODULE_PLAIN,
257
    MODULE_UMD,
258
    MODULE_ES
259
}
260
```
261

262
## Task Dependencies and Ordering
263

264
### Compilation Task Dependencies
265

266
```kotlin
267
// Ensure test compilation depends on main compilation
268
tasks.named("compileTestKotlin") {
269
    dependsOn("compileKotlin")
270
}
271

272
// Custom task dependencies
273
tasks.register("customCompile") {
274
    dependsOn(tasks.withType<KotlinCompile>())
275
}
276
```
277

278
### Source Set Compilation
279

280
Each source set gets its own compilation task:
281

282
```kotlin
283
// Main source set
284
tasks.named<KotlinCompile>("compileKotlin")
285

286
// Test source set  
287
tasks.named<KotlinCompile>("compileTestKotlin")
288

289
// Custom source set
290
sourceSets {
291
    create("integration") {
292
        // Creates compileIntegrationKotlin task
293
    }
294
}
295
```
296

297
## Compiler Tool Configurations
298

299
### Kapt Configuration
300

301
```kotlin { .api }
302
tasks.withType<KaptTask>().configureEach {
303
    useBuildCache = false
304
}
305

306
kapt {
307
    correctErrorTypes = true
308
    useBuildCache = false
309
    mapDiagnosticLocations = true
310
    arguments {
311
        arg("dagger.hilt.shareTestComponents", "true")
312
    }
313
}
314
```
315

316
### KSP (Kotlin Symbol Processing)
317

318
```kotlin
319
// When using KSP plugin
320
tasks.withType<KspTask>().configureEach {
321
    // KSP-specific configuration
322
}
323
```