or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

caching.mdcompiled-scripts.mdconfiguration.mddependencies.mdevaluators.mdindex.mdutilities.md
tile.json

tessl/maven-org-jetbrains-kotlin--kotlin-scripting-jvm

Kotlin JVM scripting support library that provides core functionality for executing and evaluating Kotlin scripts on the JVM platform

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlin/kotlin-scripting-jvm@2.2.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlin--kotlin-scripting-jvm@2.2.0

index.mddocs/

Kotlin Scripting JVM

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.

Package Information

  • Package Name: org.jetbrains.kotlin:kotlin-scripting-jvm
  • Package Type: maven
  • Language: Kotlin
  • Installation: 
    implementation("org.jetbrains.kotlin:kotlin-scripting-jvm:2.2.0")

Core Imports

import kotlin.script.experimental.jvm.*
import kotlin.script.experimental.jvm.util.*

For specific functionality:

// Configuration
import kotlin.script.experimental.jvm.JvmScriptingHostConfigurationBuilder
import kotlin.script.experimental.jvm.JvmScriptCompilationConfigurationBuilder
import kotlin.script.experimental.jvm.JvmScriptEvaluationConfigurationBuilder

// Evaluators
import kotlin.script.experimental.jvm.BasicJvmScriptEvaluator
import kotlin.script.experimental.jvm.BasicJvmReplEvaluator

// Dependencies
import kotlin.script.experimental.jvm.JvmDependency
import kotlin.script.experimental.jvm.JvmDependencyFromClassLoader

// Compiled Scripts
import kotlin.script.experimental.jvm.impl.KJvmCompiledScript

Basic Usage

import kotlin.script.experimental.api.*
import kotlin.script.experimental.jvm.*
import kotlin.script.experimental.host.toScriptSource

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

// Configure compilation
val compilationConfig = ScriptCompilationConfiguration {
    jvm {
        dependenciesFromCurrentContext(wholeClasspath = true)
    }
}

// Configure evaluation
val evaluationConfig = ScriptEvaluationConfiguration {
    jvm {
        baseClassLoader(Thread.currentThread().contextClassLoader)
    }
}

// Compile and evaluate script
val compiledScript = /* compile with your compiler */
val result = evaluator(compiledScript, evaluationConfig)

Architecture

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

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

Capabilities

Configuration System

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

interface JvmScriptingHostConfigurationKeys
open class JvmScriptingHostConfigurationBuilder : PropertiesCollection.Builder
interface JvmScriptCompilationConfigurationKeys  
open class JvmScriptCompilationConfigurationBuilder : PropertiesCollection.Builder
interface JvmScriptEvaluationConfigurationKeys
open class JvmScriptEvaluationConfigurationBuilder : PropertiesCollection.Builder

Configuration System

Dependency Management

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

data class JvmDependency(val classpath: List<File>) : ScriptDependency
class JvmDependencyFromClassLoader(
    val classLoaderGetter: ClassLoaderByConfiguration
) : ScriptDependency

typealias ClassLoaderByConfiguration = (ScriptCompilationConfiguration) -> ClassLoader

Dependency Management

Script Evaluators

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

open class BasicJvmScriptEvaluator : ScriptEvaluator {
    suspend operator fun invoke(
        compiledScript: CompiledScript,
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration
    ): ResultWithDiagnostics<EvaluationResult>
}

class BasicJvmReplEvaluator(
    val scriptEvaluator: ScriptEvaluator = BasicJvmScriptEvaluator()
) : ReplEvaluator<CompiledSnippet, KJvmEvaluatedSnippet>

Script Evaluators

Compiled Scripts and Modules

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

open class KJvmCompiledScript : CompiledScript, Serializable {
    override val sourceLocationId: String?
    override val compilationConfiguration: ScriptCompilationConfiguration
    val scriptClassFQName: String
    override val resultField: Pair<String, KotlinType>?
    
    override suspend fun getClass(
        scriptEvaluationConfiguration: ScriptEvaluationConfiguration?
    ): ResultWithDiagnostics<KClass<*>>
}

interface KJvmCompiledModule {
    fun createClassLoader(baseClassLoader: ClassLoader?): ClassLoader
}

Compiled Scripts

Utility Functions

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

object KotlinJars {
    val compilerClasspath: List<File>
    val stdlib: File
    val scriptRuntime: File
    val kotlinScriptStandardJars: List<File>
    
    fun getLib(
        propertyName: String,
        jarName: String, 
        markerClass: KClass<*>,
        classLoader: ClassLoader? = null
    ): File?
}

Utility Functions

Caching System

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

interface CompiledJvmScriptsCache {
    fun get(
        script: SourceCode,
        scriptCompilationConfiguration: ScriptCompilationConfiguration
    ): CompiledScript?
    
    fun store(
        compiledScript: CompiledScript,
        script: SourceCode,
        scriptCompilationConfiguration: ScriptCompilationConfiguration
    )
    
    object NoCache : CompiledJvmScriptsCache
}

Caching System

Types

Core Configuration Types

// Property keys for JVM-specific configuration
val ScriptingHostConfiguration.jdkHome: PropertiesCollection.Key<File?>
val ScriptingHostConfiguration.baseClassLoader: PropertiesCollection.Key<ClassLoader?>
val ScriptCompilationConfiguration.jdkHome: PropertiesCollection.Key<File?>
val ScriptCompilationConfiguration.jvmTarget: PropertiesCollection.Key<String>
val ScriptEvaluationConfiguration.baseClassLoader: PropertiesCollection.Key<ClassLoader?>
val ScriptEvaluationConfiguration.lastSnippetClassLoader: PropertiesCollection.Key<ClassLoader?>
val ScriptEvaluationConfiguration.loadDependencies: PropertiesCollection.Key<Boolean>
val ScriptEvaluationConfiguration.mainArguments: PropertiesCollection.Key<List<String>?>

Evaluation Result Types

class KJvmEvaluatedSnippet(
    compiledSnippet: CompiledSnippet,
    configuration: ScriptEvaluationConfiguration,
    result: ResultValue
) : EvaluatedSnippet {
    override val compiledSnippet: CompiledScript
    override val configuration: ScriptEvaluationConfiguration  
    override val result: ResultValue
}

Utility Types

data class AbsSourceCodePosition(
    val line: Int,
    val col: Int, 
    val absolutePos: Int
) : Serializable

open class SnippetsHistory<CompiledT, ResultT>(
    startingHistory: CompiledHistoryList<CompiledT, ResultT> = emptyList()
) : Serializable {
    val items: List<CompiledHistoryItem<CompiledT, ResultT>>
    fun add(line: CompiledT, value: ResultT)
    fun lastItem(): CompiledHistoryItem<CompiledT, ResultT>?
    fun lastValue(): ResultT?
    fun isEmpty(): Boolean
    fun isNotEmpty(): Boolean
}

typealias CompiledHistoryItem<CompiledT, ResultT> = Pair<CompiledT, ResultT>

Exception Types

class ClasspathExtractionException(message: String) : Exception