0
# Configuration System
1

2
The configuration system provides JVM-specific builders and properties for configuring host environment, compilation settings, and evaluation parameters. It offers type-safe configuration with sensible defaults and extension properties for JVM-specific settings.
3

4
## Capabilities
5

6
### Host Configuration
7

8
Configure the JVM environment for script hosting, including JDK settings and base ClassLoader configuration.
9

10
```kotlin { .api }
11
interface JvmScriptingHostConfigurationKeys
12

13
open class JvmScriptingHostConfigurationBuilder : PropertiesCollection.Builder {
14
    companion object : JvmScriptingHostConfigurationKeys
15
}
16

17
// Extension property to access JVM host configuration builder
18
val ScriptingHostConfiguration.Builder.jvm: JvmScriptingHostConfigurationBuilder
19

20
// Default configuration instance
21
val defaultJvmScriptingHostConfiguration: ScriptingHostConfiguration
22
```
23

24
**Configuration Properties:**
25

26
```kotlin { .api }
27
// JDK home directory property
28
val ScriptingHostConfiguration.jdkHome: PropertiesCollection.Key<File?>
29

30
// Base classloader property with default value
31
val ScriptingHostConfiguration.baseClassLoader: PropertiesCollection.Key<ClassLoader?>
32
```
33

34
**Usage Example:**
35

36
```kotlin
37
import kotlin.script.experimental.api.*
38
import kotlin.script.experimental.jvm.*
39

40
val hostConfig = ScriptingHostConfiguration {
41
    jvm {
42
        jdkHome = File("/usr/lib/jvm/java-11-openjdk")
43
        baseClassLoader = Thread.currentThread().contextClassLoader
44
    }
45
}
46
```
47

48
### Compilation Configuration
49

50
Configure JVM-specific compilation settings including JDK version, target platform, and dependency resolution.
51

52
```kotlin { .api }
53
interface JvmScriptCompilationConfigurationKeys
54

55
open class JvmScriptCompilationConfigurationBuilder : PropertiesCollection.Builder {
56
    companion object : JvmScriptCompilationConfigurationKeys
57
}
58

59
// Extension property to access JVM compilation configuration builder  
60
val ScriptCompilationConfiguration.Builder.jvm: JvmScriptCompilationConfigurationBuilder
61
```
62

63
**Configuration Properties:**
64

65
```kotlin { .api }
66
// JDK home directory for compilation
67
val ScriptCompilationConfiguration.jdkHome: PropertiesCollection.Key<File?>
68

69
// JVM target version (e.g., "1.8", "11", "17")
70
val ScriptCompilationConfiguration.jvmTarget: PropertiesCollection.Key<String>
71
```
72

73
**Usage Example:**
74

75
```kotlin
76
val compilationConfig = ScriptCompilationConfiguration {
77
    jvm {
78
        jdkHome = File("/usr/lib/jvm/java-17-openjdk")
79
        jvmTarget = "17"
80
        dependenciesFromCurrentContext(wholeClasspath = true)
81
    }
82
}
83
```
84

85
### Evaluation Configuration
86

87
Configure script evaluation environment including ClassLoader settings, dependency loading, and execution parameters.
88

89
```kotlin { .api }
90
interface JvmScriptEvaluationConfigurationKeys
91

92
open class JvmScriptEvaluationConfigurationBuilder : PropertiesCollection.Builder {
93
    companion object : JvmScriptEvaluationConfigurationBuilder()
94
}
95

96
// Extension property to access JVM evaluation configuration builder
97
val ScriptEvaluationConfiguration.Builder.jvm: JvmScriptEvaluationConfigurationBuilder
98
```
99

100
**Configuration Properties:**
101

102
```kotlin { .api }
103
// Base classloader for script execution
104
val ScriptEvaluationConfiguration.baseClassLoader: PropertiesCollection.Key<ClassLoader?>
105

106
// Classloader of last snippet (for REPL scenarios)
107
val ScriptEvaluationConfiguration.lastSnippetClassLoader: PropertiesCollection.Key<ClassLoader?>
108

109
// Whether to load dependencies before evaluation (default: true)
110
val ScriptEvaluationConfiguration.loadDependencies: PropertiesCollection.Key<Boolean>
111

112
// Arguments for main method execution
113
val ScriptEvaluationConfiguration.mainArguments: PropertiesCollection.Key<List<String>?>
114
```
115

116
**Usage Example:**
117

118
```kotlin
119
val evaluationConfig = ScriptEvaluationConfiguration {
120
    jvm {
121
        baseClassLoader = Thread.currentThread().contextClassLoader
122
        loadDependencies = true
123
        mainArguments = listOf("arg1", "arg2")
124
    }
125
}
126
```
127

128
### Dependency Configuration Extensions
129

130
Extension functions for configuring dependencies from various sources including current execution context, specific classes, and ClassLoaders.
131

132
```kotlin { .api }
133
/**
134
 * Configure dependencies from classes in the current classpath context
135
 */
136
fun JvmScriptCompilationConfigurationBuilder.dependenciesFromClassContext(
137
    vararg classes: KClass<*>,
138
    wholeClasspath: Boolean = false
139
)
140

141
/**
142
 * Configure dependencies from current execution context
143
 */
144
fun JvmScriptCompilationConfigurationBuilder.dependenciesFromCurrentContext(
145
    wholeClasspath: Boolean = false
146
)
147

148
/**
149
 * Configure dependencies from a specific ClassLoader
150
 */
151
fun JvmScriptCompilationConfigurationBuilder.dependenciesFromClassloader(
152
    classLoader: ClassLoader,
153
    wholeClasspath: Boolean = false
154
)
155
```
156

157
**Usage Examples:**
158

159
```kotlin
160
// From specific classes
161
val config1 = ScriptCompilationConfiguration {
162
    jvm {
163
        dependenciesFromClassContext(String::class, List::class)
164
    }
165
}
166

167
// From current context with full classpath
168
val config2 = ScriptCompilationConfiguration {
169
    jvm {
170
        dependenciesFromCurrentContext(wholeClasspath = true)
171
    }
172
}
173

174
// From specific ClassLoader
175
val config3 = ScriptCompilationConfiguration {
176
    jvm {
177
        dependenciesFromClassloader(
178
            MyClass::class.java.classLoader,
179
            wholeClasspath = false
180
        )
181
    }
182
}
183
```
184

185
### Classpath Management
186

187
Utility functions for managing and updating script compilation classpath.
188

189
```kotlin { .api }
190
/**
191
 * Create new configuration with updated classpath
192
 */
193
fun ScriptCompilationConfiguration.withUpdatedClasspath(
194
    classpath: Collection<File>
195
): ScriptCompilationConfiguration
196

197
/**
198
 * Update classpath in configuration builder
199
 */
200
fun ScriptCompilationConfiguration.Builder.updateClasspath(
201
    classpath: Collection<File>?
202
)
203

204
/**
205
 * Update classpath in JVM configuration builder
206
 */  
207
fun JvmScriptCompilationConfigurationBuilder.updateClasspath(
208
    classpath: Collection<File>?
209
)
210
```
211

212
**Usage Example:**
213

214
```kotlin
215
import java.io.File
216

217
val originalConfig = ScriptCompilationConfiguration {
218
    jvm {
219
        dependenciesFromCurrentContext()
220
    }
221
}
222

223
val additionalJars = listOf(
224
    File("/path/to/library1.jar"),
225
    File("/path/to/library2.jar")
226
)
227

228
val updatedConfig = originalConfig.withUpdatedClasspath(additionalJars)
229
```
230

231
### Script Class Resolution
232

233
Configure how scripting classes are resolved and loaded in the JVM environment.
234

235
```kotlin { .api }
236
interface GetScriptingClassByClassLoader : GetScriptingClass {
237
    operator fun invoke(
238
        classType: KotlinType,
239
        contextClassLoader: ClassLoader?,
240
        hostConfiguration: ScriptingHostConfiguration
241
    ): KClass<*>
242
}
243

244
class JvmGetScriptingClass : GetScriptingClassByClassLoader, Serializable {
245
    override fun invoke(
246
        classType: KotlinType,
247
        contextClass: KClass<*>,
248
        hostConfiguration: ScriptingHostConfiguration
249
    ): KClass<*>
250
    
251
    override operator fun invoke(
252
        classType: KotlinType,
253
        contextClassLoader: ClassLoader?,
254
        hostConfiguration: ScriptingHostConfiguration
255
    ): KClass<*>
256
}
257
```
258

259
This class resolution system enables proper loading of scripting-related classes in different ClassLoader contexts, essential for modular applications and plugin systems.