0
# Configuration System
1

2
Comprehensive configuration management providing type-safe, thread-safe storage for compiler settings and options. The configuration system uses a key-value approach with strongly-typed keys to ensure type safety and prevent configuration errors.
3

4
## Capabilities
5

6
### CompilerConfiguration
7

8
Central thread-safe configuration container managing all compiler settings and options.
9

10
```kotlin { .api }
11
/**
12
 * Thread-safe configuration container for compiler settings
13
 * Uses strongly-typed keys to ensure type safety
14
 */
15
class CompilerConfiguration {
16
    /** Get configuration value for the specified key, returns null if not set */
17
    fun <T> get(key: CompilerConfigurationKey<T>): T?
18
    
19
    /** Set configuration value for the specified key */
20
    fun <T> put(key: CompilerConfigurationKey<T>, value: T): Unit
21
    
22
    /** Get configuration value for the specified key, throws if not set */
23
    fun <T> getNotNull(key: CompilerConfigurationKey<T>): T
24
    
25
    /** Get boolean configuration value, returns false if not set */
26
    fun getBoolean(key: CompilerConfigurationKey<Boolean>): Boolean
27
    
28
    /** Get list configuration value, returns empty list if not set */
29
    fun <T> getList(key: CompilerConfigurationKey<List<T>>): List<T>
30
    
31
    /** Add value to list configuration */
32
    fun <T> add(key: CompilerConfigurationKey<List<T>>, value: T): Unit
33
    
34
    /** Add all values to list configuration */
35
    fun <T> addAll(key: CompilerConfigurationKey<List<T>>, values: Collection<T>): Unit
36
    
37
    /** Create a copy of this configuration */
38
    fun copy(): CompilerConfiguration
39
    
40
    /** Set message collector for this configuration */
41
    var messageCollector: MessageCollector
42
}
43
```
44

45
**Usage Examples:**
46

47
```kotlin
48
val configuration = CompilerConfiguration()
49

50
// Basic configuration
51
configuration.put(CommonConfigurationKeys.MODULE_NAME, "my-module")
52
configuration.put(JVMConfigurationKeys.OUTPUT_DIRECTORY, File("build/classes"))
53
configuration.put(JVMConfigurationKeys.JVM_TARGET, JvmTarget.JVM_17)
54

55
// List configuration
56
configuration.add(CLIConfigurationKeys.CONTENT_ROOTS, JavaSourceRoot(File("src/main/java")))
57
configuration.add(CLIConfigurationKeys.CONTENT_ROOTS, KotlinSourceRoot(File("src/main/kotlin")))
58

59
// Retrieving values
60
val moduleName = configuration.getNotNull(CommonConfigurationKeys.MODULE_NAME)
61
val outputDir = configuration.get(JVMConfigurationKeys.OUTPUT_DIRECTORY)
62
val sources = configuration.getList(CLIConfigurationKeys.CONTENT_ROOTS)
63

64
// Boolean configuration
65
configuration.put(JVMConfigurationKeys.INCLUDE_RUNTIME, true)
66
val includeRuntime = configuration.getBoolean(JVMConfigurationKeys.INCLUDE_RUNTIME)
67
```
68

69
### K2JVMCompilerArguments
70

71
JVM-specific compiler configuration arguments providing all options for JVM compilation.
72

73
```kotlin { .api }
74
/**
75
 * JVM-specific compiler arguments extending common compiler arguments
76
 * Contains all JVM compilation options and settings
77
 */
78
class K2JVMCompilerArguments : CommonCompilerArguments() {
79
    /** Output directory for compiled classes */
80
    var destination: String? = null
81
    
82
    /** Classpath for compilation (colon/semicolon separated) */
83
    var classpath: String? = null
84
    
85
    /** Include Kotlin runtime in the output JAR */
86
    var includeRuntime: Boolean = false
87
    
88
    /** Path to JDK home directory */
89
    var jdkHome: String? = null
90
    
91
    /** JVM target version (1.8, 9, 10, 11, 15, 17, 19, 20, 21) */
92
    var jvmTarget: String = JvmTarget.DEFAULT.description
93
    
94
    /** Generate Java 8+ parameter metadata */
95
    var javaParameters: Boolean = false
96
    
97
    /** Enable/disable Java module support */
98
    var javaModulePath: String? = null
99
    
100
    /** Module name for the compiled module */
101
    var moduleName: String? = null
102
    
103
    /** Enable/disable assertions in JVM */
104
    var assertionsMode: JVMAssertionsMode = JVMAssertionsMode.DEFAULT
105
    
106
    /** Paths to JAR files containing annotation processors */
107
    var pluginClasspaths: Array<String>? = null
108
    
109
    /** Options to pass to annotation processors */
110
    var pluginOptions: Array<String>? = null
111
    
112
    /** Enable/disable use of type annotations in the JVM bytecode */
113
    var useTypeTable: Boolean = true
114
    
115
    /** Enable/disable use of SAM conversions */
116
    var samConversions: String = "class"
117
    
118
    /** Enable/disable lambda code generation optimizations */
119
    var lambdas: String = "class"
120
    
121
    /** Enable/disable use of old Java 6 targets */
122
    var useOldBackend: Boolean = false
123
}
124
```
125

126
### CommonCompilerArguments
127

128
Base compiler arguments shared across all Kotlin compilation targets.
129

130
```kotlin { .api }
131
/**
132
 * Base compiler arguments shared across all platforms
133
 * Contains language version, API version, and common settings
134
 */
135
abstract class CommonCompilerArguments {
136
    /** Language version (1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0) */
137
    var languageVersion: String? = null
138
    
139
    /** API version (1.4, 1.5, 1.6, 1.7, 1.8, 1.9, 2.0) */
140
    var apiVersion: String? = null
141
    
142
    /** Enable verbose output */
143
    var verbose: Boolean = false
144
    
145
    /** Treat all warnings as errors */
146
    var allWarningsAsErrors: Boolean = false
147
    
148
    /** Report all warnings, even those normally suppressed */
149
    var reportAllWarnings: Boolean = false
150
    
151
    /** Suppress all warnings */
152
    var suppressWarnings: Boolean = false
153
    
154
    /** Enable experimental language features */
155
    var useExperimental: Array<String>? = null
156
    
157
    /** Require explicit API mode */
158
    var explicitApi: String? = null
159
    
160
    /** Enable progressive compiler mode */
161
    var progressive: Boolean = false
162
    
163
    /** Disable optimization */
164
    var noOptimize: Boolean = false
165
    
166
    /** Free-form compiler arguments */
167
    var freeArgs: List<String> = emptyList()
168
}
169
```
170

171
### Configuration Keys
172

173
Strongly-typed keys for accessing configuration values.
174

175
```kotlin { .api }
176
/**
177
 * Common configuration keys used across all platforms
178
 */
179
object CommonConfigurationKeys {
180
    /** Module name for compilation */
181
    val MODULE_NAME: CompilerConfigurationKey<String>
182
    
183
    /** Language version settings */
184
    val LANGUAGE_VERSION_SETTINGS: CompilerConfigurationKey<LanguageVersionSettings>
185
    
186
    /** Message collector for diagnostics */
187
    val MESSAGE_COLLECTOR_KEY: CompilerConfigurationKey<MessageCollector>
188
    
189
    /** Use K2 compiler frontend */
190
    val USE_FIR: CompilerConfigurationKey<Boolean>
191
    
192
    /** Metadata version */
193
    val METADATA_VERSION: CompilerConfigurationKey<BinaryVersion>
194
    
195
    /** Disable intrinsics */
196
    val DISABLE_INTRINSICS: CompilerConfigurationKey<Boolean>
197
    
198
    /** Phase configuration */
199
    val PHASE_CONFIG: CompilerConfigurationKey<PhaseConfig>
200
}
201

202
/**
203
 * JVM-specific configuration keys
204
 */
205
object JVMConfigurationKeys {
206
    /** Output directory for compiled classes */
207
    val OUTPUT_DIRECTORY: CompilerConfigurationKey<File>
208
    
209
    /** Output JAR file */
210
    val OUTPUT_JAR: CompilerConfigurationKey<File>
211
    
212
    /** JVM target version */
213
    val JVM_TARGET: CompilerConfigurationKey<JvmTarget>
214
    
215
    /** Include Kotlin runtime in output */
216
    val INCLUDE_RUNTIME: CompilerConfigurationKey<Boolean>
217
    
218
    /** Incremental compilation components */
219
    val INCREMENTAL_COMPILATION_COMPONENTS: CompilerConfigurationKey<IncrementalCompilationComponents>
220
    
221
    /** Disable optimizations */
222
    val DISABLE_OPTIMIZATION: CompilerConfigurationKey<Boolean>
223
    
224
    /** Use type table in bytecode */
225
    val USE_TYPE_TABLE: CompilerConfigurationKey<Boolean>
226
    
227
    /** Assertions mode */
228
    val ASSERTIONS_MODE: CompilerConfigurationKey<JVMAssertionsMode>
229
}
230

231
/**
232
 * CLI-specific configuration keys
233
 */
234
object CLIConfigurationKeys {
235
    /** Content roots (source directories) */
236
    val CONTENT_ROOTS: CompilerConfigurationKey<List<ContentRoot>>
237
    
238
    /** Original message collector */
239
    val ORIGINAL_MESSAGE_COLLECTOR_KEY: CompilerConfigurationKey<MessageCollector>
240
    
241
    /** Performance manager */
242
    val PERF_MANAGER: CompilerConfigurationKey<PerformanceManager>
243
    
244
    /** Allow Kotlin sources alongside Java */
245
    val ALLOW_KOTLIN_ALONGSIDE_JAVA_SOURCES: CompilerConfigurationKey<Boolean>
246
}
247
```
248

249
**Advanced Configuration Examples:**
250

251
```kotlin
252
// Complex configuration setup
253
val configuration = CompilerConfiguration().apply {
254
    // Language settings
255
    put(CommonConfigurationKeys.LANGUAGE_VERSION_SETTINGS, 
256
        LanguageVersionSettingsImpl(LanguageVersion.KOTLIN_2_0, ApiVersion.KOTLIN_2_0))
257
    
258
    // JVM settings
259
    put(JVMConfigurationKeys.JVM_TARGET, JvmTarget.JVM_17)
260
    put(JVMConfigurationKeys.OUTPUT_DIRECTORY, File("build/classes"))
261
    put(JVMConfigurationKeys.INCLUDE_RUNTIME, false)
262
    put(JVMConfigurationKeys.USE_TYPE_TABLE, true)
263
    
264
    // Source roots
265
    add(CLIConfigurationKeys.CONTENT_ROOTS, 
266
        KotlinSourceRoot("src/main/kotlin", isCommon = false))
267
    add(CLIConfigurationKeys.CONTENT_ROOTS, 
268
        JavaSourceRoot(File("src/main/java")))
269
    
270
    // Message collection
271
    messageCollector = PrintingMessageCollector(System.err, MessageRenderer.PLAIN, true)
272
    
273
    // Performance tracking
274
    put(CLIConfigurationKeys.PERF_MANAGER, ProfilingCompilerPerformanceManager())
275
}
276

277
// Using with incremental compilation
278
val incrementalComponents = IncrementalCompilationComponents.create()
279
configuration.put(JVMConfigurationKeys.INCREMENTAL_COMPILATION_COMPONENTS, incrementalComponents)
280
```
281

282
## Type Definitions
283

284
```kotlin { .api }
285
/**
286
 * JVM target versions
287
 */
288
enum class JvmTarget(val description: String) {
289
    JVM_1_8("1.8"),
290
    JVM_9("9"),
291
    JVM_10("10"), 
292
    JVM_11("11"),
293
    JVM_15("15"),
294
    JVM_17("17"),
295
    JVM_19("19"),
296
    JVM_20("20"),
297
    JVM_21("21");
298
    
299
    companion object {
300
        val DEFAULT: JvmTarget = JVM_1_8
301
    }
302
}
303

304
/**
305
 * JVM assertions mode
306
 */
307
enum class JVMAssertionsMode {
308
    DEFAULT, ENABLE, DISABLE
309
}
310

311
/**
312
 * Content root types for source directories
313
 */
314
sealed class ContentRoot
315

316
data class KotlinSourceRoot(
317
    val path: String,
318
    val isCommon: Boolean = false
319
) : ContentRoot()
320

321
data class JavaSourceRoot(
322
    val file: File
323
) : ContentRoot()
324
```