Kotlin Gradle Plugin (KGP)

Active contributors: Yahor Berdnikau, Andrey Yastrebov, Timofey Solonin

The Kotlin Gradle Plugin (KGP) is the Gradle integration for Kotlin: the kotlin("jvm"), kotlin("multiplatform"), kotlin("js"), kotlin("android") plugin IDs and the DSL behind them. It is one of the largest single subprojects in the repository and one of the most actively iterated — its public API file (kotlin-gradle-plugin.api) is among the most frequently modified files in the recent history.

Purpose

Translate user-friendly Gradle DSL configuration (kotlin { jvmToolchain(17); compilerOptions { ... } }) into compile/test/dist tasks that invoke the Kotlin compiler with the right arguments, classpath, and incremental state. Handle Multiplatform (multi-target), Android, JS, Wasm, and Native target specifics. Integrate with Gradle's task graph, build cache, and configuration cache.

Directory layout

libraries/tools/
├── kotlin-gradle-plugin/                    The plugin (code that runs in Gradle)
├── kotlin-gradle-plugin-api/                Stable public DSL/API surface
├── kotlin-gradle-plugin-idea/               IDE import surface (used by IntelliJ)
├── kotlin-gradle-plugin-idea-proto/         Protobuf for IDE import
├── kotlin-gradle-plugin-idea-for-compatibility-tests/
├── kotlin-gradle-plugin-annotations/        Annotations consumed by user build scripts
├── kotlin-gradle-plugin-dsl-codegen/        Generators for DSL types
├── kotlin-gradle-plugin-tcs-android/        Android target-config helpers
├── kotlin-gradle-plugin-integration-tests/  End-to-end tests with real Gradle
├── kotlin-gradle-plugin-test-utils-embeddable/
├── kotlin-gradle-plugin-integration-tests-buildscript/
├── kotlin-gradle-plugins-bom/               BOM listing all KGP-related artifacts
├── kotlin-gradle-build-metrics/             Build-metrics integration
├── kotlin-gradle-statistics/                Build statistics
├── kotlin-gradle-compiler-types/            Compiler-types view used in DSL
├── gradle/                                  Common Gradle helpers
├── kotlin-tooling-core/                     Shared utilities used by KGP + IDE
├── kotlin-tooling-metadata/                 Project-metadata format
└── ...

Key abstractions

Type	Where	Role
KotlinPluginWrapper	libraries/tools/kotlin-gradle-plugin/.../KotlinPluginWrapper.kt	The actual Plugin<Project>.
KotlinProjectExtension (and friends)	libraries/tools/kotlin-gradle-plugin/.../dsl/...	Top-level kotlin { } extension.
KotlinTarget, KotlinCompilation	kotlin-gradle-plugin-api/.../...	Multiplatform target / compilation primitives.
KotlinCompile	libraries/tools/kotlin-gradle-plugin/.../tasks/KotlinCompile.kt	The Gradle task that runs the JVM compiler.
Kotlin2JsCompile, KotlinNativeCompile, KotlinCompileCommon	libraries/tools/kotlin-gradle-plugin/.../tasks/...	Per-target compile tasks.
KotlinJsCompilerOptions, KotlinJvmCompilerOptions, ...	kotlin-gradle-plugin-api/.../compilerOptions/...	DSL types for compiler options.

DSL surface

// Typical user build.gradle.kts
plugins {
    kotlin("jvm") version "2.1.0"
}

kotlin {
    jvmToolchain(17)
    compilerOptions {
        languageVersion.set(KotlinVersion.KOTLIN_2_1)
        freeCompilerArgs.add("-Xinline-classes")
    }
}

The DSL types (KotlinProjectExtension, KotlinJvmCompilerOptions, ...) live in kotlin-gradle-plugin-api/. The plugin code that backs them is in kotlin-gradle-plugin/. The kotlin-gradle-plugin-api jar is the "API surface" that user build scripts compile against; it has its own checked-in .api dump (one of the most-modified files in the repo).

Incremental compilation and Build Tools API

KGP no longer talks to the compiler internals directly; it goes through the Build Tools API (BTAPI, see build-tools.md). This decouples plugin releases from compiler releases and lets BTAPI's compatibility wrappers handle version mismatches.

When a KotlinCompile task runs, it builds a typed JvmCompilerArguments object, hands it to BTAPI, and gets back a result. BTAPI internally chooses between in-process compilation and the long-running compile daemon based on configuration.

graph LR
    KotlinCompile["Gradle KotlinCompile task"] --> Args["build JvmCompilerArguments"]
    Args --> BTAPI["BTAPI CompilationService"]
    BTAPI --> Daemon["compile daemon"]
    BTAPI --> InProc["in-process compiler"]
    Daemon --> Cls["class files"]
    InProc --> Cls
    Cls --> Out["task outputs"]

Multiplatform

The Multiplatform support (kotlin("multiplatform")) is the heart of KGP's complexity. It manages:

• Targets — jvm, js, wasmJs, wasmWasi, linuxX64, iosArm64, ...
• Source sets — commonMain, commonTest, plus per-target sets and intermediate ones (e.g., nativeMain).
• klib production and consumption — compileKotlinNative* tasks produce klibs; downstream targets consume them.
• Default hierarchy templates — automatically wire intermediate source sets for typical KMP setups.
• Compose Multiplatform / KMM — composes with the Compose plugin, the Android Gradle plugin, and Apple-target tooling.

The implementation is split across kotlin-gradle-plugin/, with target-specific bits in kotlin-multiplatform/, kotlin-gradle-plugin-tcs-android/, and the IDE-import side in kotlin-gradle-plugin-idea/.

IDE import

kotlin-gradle-plugin-idea/ is what IntelliJ IDEA queries to understand a Kotlin Gradle project's structure. It exposes (via Gradle tooling-API + protobuf in kotlin-gradle-plugin-idea-proto/) the source-set graph, dependency tree, and target configuration.

Tests

Test family	Where	Speed
Plugin unit tests	kotlin-gradle-plugin/test/...	Fast
API tests	kotlin-gradle-plugin-api/test/...	Fast
Integration tests	kotlin-gradle-plugin-integration-tests/	Very slow — runs real Gradle builds
Compatibility tests	kotlin-gradle-plugin-idea-for-compatibility-tests/	Slow

The integration tests have their own AGENTS.md (libraries/tools/kotlin-gradle-plugin-integration-tests/AGENTS.md) — required reading.

API stability

The KGP-API jar follows strict binary compatibility: any change visible in kotlin-gradle-plugin.api requires either a deprecation cycle or a new artifact. Update the .api dump in the same commit; CI fails the build otherwise.

The plugin jar itself has more freedom for internal changes but is still careful about behavioral compatibility — a build script that compiled with KGP 2.1 should keep working with 2.2.

Integration points

• Consumed by: every Kotlin user that builds with Gradle (probably the majority).
• Talks to: BTAPI → daemon / in-process compiler → standard library / klibs.
• Co-travels with: the Android Gradle plugin (KGP detects AGP and adapts), the Compose plugin, and the kotlinx.serialization plugin.

Where to start

DSL changes → libraries/tools/kotlin-gradle-plugin-api/. Behavior changes → libraries/tools/kotlin-gradle-plugin/. Multiplatform → its dedicated subdirectories. Tests → run an integration test with --info to see real Gradle output.

Read libraries/tools/kotlin-gradle-plugin/AGENTS.md and libraries/tools/kotlin-gradle-plugin-api/AGENTS.md first.

See Build Tools API, Daemon, and the plugins overview (some compiler plugins are wrapped in KGP DSL).