kotlin-gradle-plugin

<essential_principles>

The Kotlin Gradle Plugin (KGP) integrates Kotlin compilation into Gradle builds. It shares its version number with Kotlin itself (e.g., KGP 2.3.21 = Kotlin 2.3.21).

Core Rules an Agent Must Know

• Apply with kotlin("jvm") or kotlin("multiplatform") in the plugins {} block. Use version catalogs for consistency.
• Use jvmToolchain(17) in the kotlin {} block to set the JDK for both Kotlin and Java compilation. This is the recommended approach — avoids jvmTarget/targetCompatibility mismatches.
• Configure compiler options at extension level via kotlin { compilerOptions {} }. Use typed values (JvmTarget.JVM_17, KotlinVersion.KOTLIN_2_3), not strings.
• kotlinOptions {} is removed. Use compilerOptions {} instead. Key migration: jvmTarget = "17" → jvmTarget.set(JvmTarget.JVM_17), freeCompilerArgs += → freeCompilerArgs.add().
• kotlin-stdlib is added automatically by KGP since 1.4. Don't declare it manually.
• Prefer KSP over kapt for annotation processing — faster, no Java stubs.
• Incremental compilation is on by default. Gradle build cache, configuration cache, and parallel execution should all be enabled.
• Add .kotlin to .gitignore — KGP stores per-project data there.
• Check KGP/Gradle/AGP version compatibility before upgrading any of the three.

</essential_principles>