0
# Kotlin Compiler Infrastructure
1
2
The Kotlin compiler infrastructure provides comprehensive compilation services for Kotlin source code targeting JVM, JavaScript, and metadata-only outputs. It offers both command-line interfaces and programmatic APIs for embedding Kotlin compilation into build tools, IDEs, and other development infrastructure.
3
4
## Package Information
5
6
- **Package Name**: org.jetbrains.kotlin:kotlin-compiler
7
- **Package Type**: maven
8
- **Language**: Kotlin/Java
9
- **Installation**: Add to build.gradle.kts: `implementation("org.jetbrains.kotlin:kotlin-compiler:2.2.20-RC2")`
10
11
## Core Imports
12
13
```kotlin
14
import org.jetbrains.kotlin.cli.jvm.K2JVMCompiler
15
import org.jetbrains.kotlin.cli.js.K2JSCompiler
16
import org.jetbrains.kotlin.cli.metadata.KotlinMetadataCompiler
17
import org.jetbrains.kotlin.cli.common.arguments.*
18
import org.jetbrains.kotlin.config.CompilerConfiguration
19
import org.jetbrains.kotlin.config.Services
20
import org.jetbrains.kotlin.platform.TargetPlatform
21
```
22
23
**External Dependencies:**
24
The Kotlin compiler depends on IntelliJ Platform components:
25
```kotlin
26
import com.intellij.openapi.Disposable
27
import com.intellij.openapi.project.Project
28
import com.intellij.mock.MockProject
29
```
30
31
## Basic Usage
32
33
```kotlin
34
import org.jetbrains.kotlin.cli.jvm.K2JVMCompiler
35
import org.jetbrains.kotlin.cli.common.arguments.K2JVMCompilerArguments
36
import org.jetbrains.kotlin.cli.common.ExitCode
37
import org.jetbrains.kotlin.config.Services
38
39
// Create compiler instance
40
val compiler = K2JVMCompiler()
41
42
// Configure compilation arguments
43
val args = K2JVMCompilerArguments().apply {
44
freeArgs = listOf("src/main/kotlin/Main.kt")
45
destination = "build/classes"
46
classpath = "lib/kotlin-stdlib.jar"
47
noStdlib = false
48
}
49
50
// Execute compilation
51
val exitCode = compiler.exec(System.err, Services.EMPTY, args)
52
if (exitCode == ExitCode.OK) {
53
println("Compilation successful")
54
}
55
```
56
57
## Architecture
58
59
The Kotlin compiler infrastructure is organized around several key architectural components:
60
61
- **CLICompiler Base Class**: Abstract foundation providing common compilation workflows and argument processing
62
- **Platform-Specific Compilers**: Concrete implementations for JVM, JavaScript, and metadata compilation targets
63
- **Configuration System**: Type-safe configuration management through strongly-typed keys and services
64
- **Plugin Architecture**: Modern K2-compatible plugin system with CompilerPluginRegistrar interface
65
- **Pipeline System**: Phase-based compilation pipeline with configurable execution stages
66
- **Environment Management**: Comprehensive project environment setup and dependency resolution
67
68
## Capabilities
69
70
### JVM Compilation
71
72
Complete JVM bytecode compilation with support for all Kotlin language features, Java interop, and advanced optimization passes.
73
74
```kotlin { .api }
75
class K2JVMCompiler : CLICompiler<K2JVMCompilerArguments>() {
76
override val platform: TargetPlatform // JvmPlatforms.defaultJvmPlatform
77
78
override fun createArguments(): K2JVMCompilerArguments
79
80
override fun doExecute(
81
arguments: K2JVMCompilerArguments,
82
configuration: CompilerConfiguration,
83
rootDisposable: Disposable,
84
paths: KotlinPaths?
85
): ExitCode
86
87
override fun doExecutePhased(
88
arguments: K2JVMCompilerArguments,
89
services: Services,
90
messageCollector: MessageCollector
91
): ExitCode
92
}
93
94
class K2JVMCompilerArguments : CommonCompilerArguments() {
95
var destination: String?
96
var classpath: String?
97
var moduleName: String?
98
var jdkHome: String?
99
var jvmTarget: String?
100
var includeRuntime: Boolean
101
}
102
```
103
104
[JVM Compilation](./jvm-compilation.md)
105
106
### JavaScript and WebAssembly Compilation
107
108
JavaScript ES5/ES6 and WebAssembly compilation with module system support and source map generation.
109
110
```kotlin { .api }
111
class K2JSCompiler : CLICompiler<K2JSCompilerArguments>() {
112
override val platform: TargetPlatform // JsPlatforms.defaultJsPlatform
113
114
override fun createArguments(): K2JSCompilerArguments
115
116
override fun doExecute(
117
arguments: K2JSCompilerArguments,
118
configuration: CompilerConfiguration,
119
rootDisposable: Disposable,
120
paths: KotlinPaths?
121
): ExitCode
122
123
override fun doExecutePhased(
124
arguments: K2JSCompilerArguments,
125
services: Services,
126
messageCollector: MessageCollector
127
): ExitCode?
128
}
129
130
class K2JSCompilerArguments : K2WasmCompilerArguments() {
131
var outputFile: String?
132
var moduleKind: String?
133
var sourceMap: Boolean
134
var sourceMapPrefix: String?
135
var libraries: String?
136
}
137
```
138
139
[JavaScript and WebAssembly Compilation](./js-wasm-compilation.md)
140
141
### Plugin Development
142
143
Modern K2 plugin architecture enabling custom compilation phases, code generation, and IDE integration.
144
145
```kotlin { .api }
146
@ExperimentalCompilerApi
147
abstract class CompilerPluginRegistrar {
148
abstract val pluginId: String
149
abstract val supportsK2: Boolean
150
151
abstract fun ExtensionStorage.registerExtensions(configuration: CompilerConfiguration)
152
153
class ExtensionStorage {
154
fun <T : Any> ProjectExtensionDescriptor<T>.registerExtension(extension: T)
155
fun registerDisposable(disposable: PluginDisposable)
156
}
157
}
158
159
@ExperimentalCompilerApi
160
interface CommandLineProcessor {
161
val pluginId: String
162
val pluginOptions: Collection<AbstractCliOption>
163
164
fun processOption(
165
option: AbstractCliOption,
166
value: String,
167
configuration: CompilerConfiguration
168
)
169
}
170
```
171
172
[Plugin Development](./plugin-development.md)
173
174
### Configuration Management
175
176
Type-safe configuration system with hierarchical key organization and service dependency injection.
177
178
```kotlin { .api }
179
class CompilerConfiguration {
180
companion object {
181
val EMPTY: CompilerConfiguration
182
}
183
184
fun <T> put(key: CompilerConfigurationKey<T>, value: T)
185
fun <T> putIfNotNull(key: CompilerConfigurationKey<T>, value: T?)
186
fun <T> get(key: CompilerConfigurationKey<T>): T?
187
fun <T> getNotNull(key: CompilerConfigurationKey<T>): T
188
fun <T> getList(key: CompilerConfigurationKey<List<T>>): List<T>
189
fun copy(): CompilerConfiguration
190
}
191
192
object CommonConfigurationKeys {
193
val MODULE_NAME: CompilerConfigurationKey<String>
194
val LANGUAGE_VERSION_SETTINGS: CompilerConfigurationKey<LanguageVersionSettings>
195
val MESSAGE_COLLECTOR_KEY: CompilerConfigurationKey<MessageCollector>
196
}
197
```
198
199
[Configuration Management](./configuration.md)
200
201
### Environment and Project Setup
202
203
Comprehensive environment management for compilation projects including dependency resolution and file system setup.
204
205
```kotlin { .api }
206
class KotlinCoreEnvironment private constructor(
207
val projectEnvironment: ProjectEnvironment,
208
val configuration: CompilerConfiguration,
209
configFiles: EnvironmentConfigFiles
210
) {
211
companion object {
212
fun createForProduction(
213
parentDisposable: Disposable,
214
configuration: CompilerConfiguration,
215
configFiles: EnvironmentConfigFiles
216
): KotlinCoreEnvironment
217
}
218
219
val project: Project
220
221
class ProjectEnvironment(
222
disposable: Disposable,
223
applicationEnvironment: KotlinCoreApplicationEnvironment,
224
configuration: CompilerConfiguration
225
) : KotlinCoreProjectEnvironment(disposable, applicationEnvironment)
226
}
227
```
228
229
[Environment Management](./environment.md)
230
231
### Message Handling and Diagnostics
232
233
Comprehensive diagnostic and message reporting system with multiple output formats and severity levels.
234
235
```kotlin { .api }
236
interface MessageCollector {
237
fun report(
238
severity: CompilerMessageSeverity,
239
message: String,
240
location: CompilerMessageSourceLocation? = null
241
)
242
}
243
244
enum class CompilerMessageSeverity {
245
EXCEPTION, ERROR, STRONG_WARNING, FIXED_WARNING, WARNING, INFO, LOGGING, OUTPUT
246
}
247
```
248
249
[Message Handling](./message-handling.md)
250
251
## Exit Codes
252
253
```kotlin { .api }
254
enum class ExitCode(val code: Int) {
255
OK(0),
256
COMPILATION_ERROR(1),
257
INTERNAL_ERROR(2),
258
SCRIPT_EXECUTION_ERROR(3),
259
OOM_ERROR(137)
260
}
261
```
262
263
## Core Types
264
265
```kotlin { .api }
266
abstract class CLICompiler<A : CommonCompilerArguments> {
267
abstract val platform: TargetPlatform
268
269
abstract fun createArguments(): A
270
271
abstract fun doExecute(
272
arguments: A,
273
configuration: CompilerConfiguration,
274
rootDisposable: Disposable,
275
paths: KotlinPaths?
276
): ExitCode
277
278
open fun doExecutePhased(
279
arguments: A,
280
services: Services,
281
messageCollector: MessageCollector
282
): ExitCode?
283
284
fun exec(errStream: PrintStream, services: Services, vararg args: String): ExitCode
285
}
286
287
open class CommonCompilerArguments : CommonToolArguments() {
288
var languageVersion: String?
289
var apiVersion: String?
290
var suppressWarnings: Boolean
291
var verbose: Boolean
292
var freeArgs: List<String>
293
}
294
295
abstract class K2WasmCompilerArguments : CommonCompilerArguments() {
296
// Base class for WebAssembly-related compilation arguments
297
}
298
299
class Services {
300
companion object {
301
val EMPTY: Services
302
}
303
304
fun <T> get(request: Class<T>): T?
305
}
306
```