0
# Kotlin Scripting JVM
1

2
Kotlin Scripting JVM provides comprehensive JVM-specific implementation of Kotlin's scripting framework. It enables embedding Kotlin scripting capabilities into applications with support for REPL evaluation, script compilation, runtime execution, dependency management, and classpath handling for JVM-based scripting environments.
3

4
## Package Information
5

6
- **Package Name**: org.jetbrains.kotlin:kotlin-scripting-jvm
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: 
10
  ```kotlin
11
  implementation("org.jetbrains.kotlin:kotlin-scripting-jvm:2.2.0")
12
  ```
13

14
## Core Imports
15

16
```kotlin
17
import kotlin.script.experimental.jvm.*
18
import kotlin.script.experimental.jvm.util.*
19
```
20

21
For specific functionality:
22

23
```kotlin
24
// Configuration
25
import kotlin.script.experimental.jvm.JvmScriptingHostConfigurationBuilder
26
import kotlin.script.experimental.jvm.JvmScriptCompilationConfigurationBuilder
27
import kotlin.script.experimental.jvm.JvmScriptEvaluationConfigurationBuilder
28

29
// Evaluators
30
import kotlin.script.experimental.jvm.BasicJvmScriptEvaluator
31
import kotlin.script.experimental.jvm.BasicJvmReplEvaluator
32

33
// Dependencies
34
import kotlin.script.experimental.jvm.JvmDependency
35
import kotlin.script.experimental.jvm.JvmDependencyFromClassLoader
36

37
// Compiled Scripts
38
import kotlin.script.experimental.jvm.impl.KJvmCompiledScript
39
```
40

41
## Basic Usage
42

43
```kotlin
44
import kotlin.script.experimental.api.*
45
import kotlin.script.experimental.jvm.*
46
import kotlin.script.experimental.host.toScriptSource
47

48
// Basic script evaluation
49
val evaluator = BasicJvmScriptEvaluator()
50
val source = "println(\"Hello, World!\")".toScriptSource()
51

52
// Configure compilation
53
val compilationConfig = ScriptCompilationConfiguration {
54
    jvm {
55
        dependenciesFromCurrentContext(wholeClasspath = true)
56
    }
57
}
58

59
// Configure evaluation
60
val evaluationConfig = ScriptEvaluationConfiguration {
61
    jvm {
62
        baseClassLoader(Thread.currentThread().contextClassLoader)
63
    }
64
}
65

66
// Compile and evaluate script
67
val compiledScript = /* compile with your compiler */
68
val result = evaluator(compiledScript, evaluationConfig)
69
```
70

71
## Architecture
72

73
The kotlin-scripting-jvm library is organized around several key components:
74

75
- **Configuration System**: Builders for host, compilation, and evaluation settings with JVM-specific extensions
76
- **Dependency Management**: Classpath handling and ClassLoader resolution for script execution
77
- **Script Evaluators**: Both standalone and REPL script execution engines
78
- **Compiled Script Representation**: Serializable script containers with module support and metadata
79
- **Utility Functions**: Classpath extraction, ClassLoader management, source code handling, and diagnostics
80
- **Compatibility Layer**: Legacy scripting API support and diagnostic mapping
81

82
## Capabilities
83

84
### Configuration System
85

86
JVM-specific configuration builders and properties for host environment, compilation settings, and evaluation parameters. Provides type-safe configuration with sensible defaults.
87

88
```kotlin { .api }
89
interface JvmScriptingHostConfigurationKeys
90
open class JvmScriptingHostConfigurationBuilder : PropertiesCollection.Builder
91
interface JvmScriptCompilationConfigurationKeys  
92
open class JvmScriptCompilationConfigurationBuilder : PropertiesCollection.Builder
93
interface JvmScriptEvaluationConfigurationKeys
94
open class JvmScriptEvaluationConfigurationBuilder : PropertiesCollection.Builder
95
```
96

97
[Configuration System](./configuration.md)
98

99
### Dependency Management
100

101
JVM classpath dependency handling including direct file dependencies, ClassLoader-based dependencies, and automatic classpath detection from context.
102

103
```kotlin { .api }
104
data class JvmDependency(val classpath: List<File>) : ScriptDependency
105
class JvmDependencyFromClassLoader(
106
    val classLoaderGetter: ClassLoaderByConfiguration
107
) : ScriptDependency
108

109
typealias ClassLoaderByConfiguration = (ScriptCompilationConfiguration) -> ClassLoader
110
```
111

112
[Dependency Management](./dependencies.md)
113

114
### Script Evaluators
115

116
Script evaluation engines supporting both standalone script execution and REPL (Read-Eval-Print Loop) scenarios with proper error handling and diagnostics.
117

118
```kotlin { .api }
119
open class BasicJvmScriptEvaluator : ScriptEvaluator {
120
    suspend operator fun invoke(
121
        compiledScript: CompiledScript,
122
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration
123
    ): ResultWithDiagnostics<EvaluationResult>
124
}
125

126
class BasicJvmReplEvaluator(
127
    val scriptEvaluator: ScriptEvaluator = BasicJvmScriptEvaluator()
128
) : ReplEvaluator<CompiledSnippet, KJvmEvaluatedSnippet>
129
```
130

131
[Script Evaluators](./evaluators.md)
132

133
### Compiled Scripts and Modules
134

135
JVM implementations of compiled scripts with serialization support, module management, and ClassLoader creation capabilities.
136

137
```kotlin { .api }
138
open class KJvmCompiledScript : CompiledScript, Serializable {
139
    override val sourceLocationId: String?
140
    override val compilationConfiguration: ScriptCompilationConfiguration
141
    val scriptClassFQName: String
142
    override val resultField: Pair<String, KotlinType>?
143
    
144
    override suspend fun getClass(
145
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration?
146
    ): ResultWithDiagnostics<KClass<*>>
147
}
148

149
interface KJvmCompiledModule {
150
    fun createClassLoader(baseClassLoader: ClassLoader?): ClassLoader
151
}
152
```
153

154
[Compiled Scripts](./compiled-scripts.md)
155

156
### Utility Functions
157

158
Comprehensive utilities for classpath extraction, ClassLoader management, source code position tracking, error reporting, and JVM-specific operations.
159

160
```kotlin { .api }
161
object KotlinJars {
162
    val compilerClasspath: List<File>
163
    val stdlib: File
164
    val scriptRuntime: File
165
    val kotlinScriptStandardJars: List<File>
166
    
167
    fun getLib(
168
        propertyName: String,
169
        jarName: String, 
170
        markerClass: KClass<*>,
171
        classLoader: ClassLoader? = null
172
    ): File?
173
}
174
```
175

176
[Utility Functions](./utilities.md)
177

178
### Caching System
179

180
Script compilation caching interface with configurable cache implementations for improved performance in repeated script execution scenarios.
181

182
```kotlin { .api }
183
interface CompiledJvmScriptsCache {
184
    fun get(
185
        script: SourceCode,
186
        scriptCompilationConfiguration: ScriptCompilationConfiguration
187
    ): CompiledScript?
188
    
189
    fun store(
190
        compiledScript: CompiledScript,
191
        script: SourceCode,
192
        scriptCompilationConfiguration: ScriptCompilationConfiguration
193
    )
194
    
195
    object NoCache : CompiledJvmScriptsCache
196
}
197
```
198

199
[Caching System](./caching.md)
200

201
## Types
202

203
### Core Configuration Types
204

205
```kotlin { .api }
206
// Property keys for JVM-specific configuration
207
val ScriptingHostConfiguration.jdkHome: PropertiesCollection.Key<File?>
208
val ScriptingHostConfiguration.baseClassLoader: PropertiesCollection.Key<ClassLoader?>
209
val ScriptCompilationConfiguration.jdkHome: PropertiesCollection.Key<File?>
210
val ScriptCompilationConfiguration.jvmTarget: PropertiesCollection.Key<String>
211
val ScriptEvaluationConfiguration.baseClassLoader: PropertiesCollection.Key<ClassLoader?>
212
val ScriptEvaluationConfiguration.lastSnippetClassLoader: PropertiesCollection.Key<ClassLoader?>
213
val ScriptEvaluationConfiguration.loadDependencies: PropertiesCollection.Key<Boolean>
214
val ScriptEvaluationConfiguration.mainArguments: PropertiesCollection.Key<List<String>?>
215
```
216

217
### Evaluation Result Types
218

219
```kotlin { .api }
220
class KJvmEvaluatedSnippet(
221
    compiledSnippet: CompiledSnippet,
222
    configuration: ScriptEvaluationConfiguration,
223
    result: ResultValue
224
) : EvaluatedSnippet {
225
    override val compiledSnippet: CompiledScript
226
    override val configuration: ScriptEvaluationConfiguration  
227
    override val result: ResultValue
228
}
229
```
230

231
### Utility Types
232

233
```kotlin { .api }
234
data class AbsSourceCodePosition(
235
    val line: Int,
236
    val col: Int, 
237
    val absolutePos: Int
238
) : Serializable
239

240
open class SnippetsHistory<CompiledT, ResultT>(
241
    startingHistory: CompiledHistoryList<CompiledT, ResultT> = emptyList()
242
) : Serializable {
243
    val items: List<CompiledHistoryItem<CompiledT, ResultT>>
244
    fun add(line: CompiledT, value: ResultT)
245
    fun lastItem(): CompiledHistoryItem<CompiledT, ResultT>?
246
    fun lastValue(): ResultT?
247
    fun isEmpty(): Boolean
248
    fun isNotEmpty(): Boolean
249
}
250

251
typealias CompiledHistoryItem<CompiledT, ResultT> = Pair<CompiledT, ResultT>
252
```
253

254
### Exception Types
255

256
```kotlin { .api }
257
class ClasspathExtractionException(message: String) : Exception
258
```