Scripting

Active contributors: Ilya Chernikov, Alexander Udalov, Dmitriy Novozhilov

libraries/scripting/ is the Kotlin script engine and ecosystem: the host that compiles and runs .kts files, the script-definition API that lets tools (Gradle, kts-launcher, Jupyter, IDE-side previewers) embed Kotlin scripts, and the JSR-223 / kotlin-main-kts launchers.

Purpose

Compile and execute .kts files in a configurable, sandboxable host. Provide a stable script-definition API so tools can declare what kinds of .kts files they support (Gradle build scripts, Kotlin worksheets, Jupyter notebooks, ...) and how the host should configure the compiler for them.

Directory layout

libraries/scripting/
├── common/                  Common types (script source, configuration)
├── common-impl/             Default implementations
├── jvm/                     JVM scripting host (compiles .kts to JVM bytecode)
├── jvm-host/                Top-level JVM host (used by build tools)
├── jvm-host-test/           Tests
├── compiler/                The scripting compiler plugin
├── compiler-plugin/         Compiler-side script handling
├── compiler-impl/           Implementation behind the compiler plugin
├── jsr223/                  JSR-223 (javax.script) adapter
├── jsr223-test/             JSR-223 tests
├── dependencies/            Dependency-resolution helpers (Maven, Ivy)
├── dependencies-maven/      Maven-specific resolver
├── dependencies-maven-all/
├── ide-services/            IDE integration helpers
├── ide-services-test/
├── intellij-test/           IntelliJ-side script tests
├── kotlinx-metadata-tests/
├── refl/                    Reflection helpers used by hosts
├── kotlin-script-runtime/   Tiny runtime jar shipped with scripts
├── test-deps/, type-providers/
└── ...

Key abstractions

Type	Where	Role
ScriptCompilationConfiguration	libraries/scripting/common/.../ScriptCompilationConfiguration.kt	Per-script-kind configuration: dependencies, default imports, compiler options.
ScriptEvaluationConfiguration	libraries/scripting/common/...	Runtime config: classpath, args, runtime services.
ScriptHost	libraries/scripting/common/...	Abstraction over a compile + run cycle.
BasicJvmScriptingHost	libraries/scripting/jvm-host/.../BasicJvmScriptingHost.kt	Default JVM host.
ScriptDefinition	libraries/scripting/...	A registered script kind (file extension + configuration).
KotlinJsr223ScriptEngine	libraries/scripting/jsr223/...	javax.script.ScriptEngine adapter.

How scripts work

graph LR
    Source[".kts source"] --> Host["BasicJvmScriptingHost"]
    Host --> Compiler["Kotlin compiler<br/>(via in-process API)"]
    Compiler --> Bytecode[".class files in memory"]
    Bytecode --> Loader["URLClassLoader"]
    Loader --> Run["MyScript.<init>()"]

A script is conceptually a Kotlin class whose body is the script. The compiler runs as usual but with extra configuration (a script template that the file extends) supplied by the host. The output classes live in memory by default; the host instantiates the script class to run it.

Script definitions

A script definition tells the compiler how to handle a particular .kts extension. For example, the Gradle Kotlin DSL has its own definition that imports Gradle types by default; Jupyter has its own with notebook-cell semantics; kotlin-main-kts has a CLI-friendly definition that supports @file:DependsOn(...) annotations for dependency declaration.

Definitions are loaded from JARs that contain a service descriptor in META-INF/kotlin/script/templates/ and a KotlinScript annotation on the template class.

kotlin-main-kts

libraries/tools/kotlin-main-kts/ (despite living under libraries/tools/, conceptually a scripting consumer) ships a kotlin-main-kts.jar that supports @file:DependsOn, @file:Repository, and @file:Import. It's the easiest way to run Kotlin scripts that fetch dependencies dynamically.

JSR-223

libraries/scripting/jsr223/ exposes Kotlin scripting through javax.script.ScriptEngine. Useful for hosts already built around JSR-223 (e.g., Apache Camel, some BPM tools).

Dependency resolution

Scripts often need libraries from Maven Central. libraries/scripting/dependencies-maven/ provides a Maven-based resolver that scripts can declare via @file:DependsOn(...). The resolver is asynchronous and caches downloads.

Integration points

• Consumers: Gradle (Kotlin DSL build scripts), Kotlin Notebook / Jupyter, kotlin-main-kts, JSR-223 hosts, the IntelliJ IDE for .kts editing.
• Backed by: the in-tree Kotlin compiler (via the same compiler API used by build tools).
• Co-travelers: KGP uses scripting for *.gradle.kts editor support, and the IDE plugin uses scripting for in-IDE evaluation.

Where to start

For a new script flavor: define a script template (an abstract class annotated with @KotlinScript) plus configuration overrides. Look at existing ones in libraries/scripting/jvm-host-test/ for examples.

For host-level changes (how scripts compile or run): libraries/scripting/jvm-host/.

For the compiler plugin that drives script-specific compilation behavior: libraries/scripting/compiler-plugin/.