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