💡

If you are looking into migrating an existing build to the Gradle Kotlin DSL, please check out the migration guide.

The kotlin-dsl plugin

When applied to a project, the kotlin-dsl Gradle plugin configures the project’s Kotlin source sets to enable Gradle Kotlin DSL features.

It is useful for all projects implementing build logic: buildSrc, included builds for build logic or Gradle plugin builds.

The kotlin-dsl plugin can be applied as follows:

buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl`
}

repositories {
    // The org.jetbrains.kotlin.jvm plugin requires a repository
    // where to download the Kotlin compiler dependencies from.
    jcenter()
}

The kotlin-dsl plugin

  • applies the org.jetbrains.kotlin.jvm plugin,

  • configures an embedded repository that contains all Kotlin libraries embedded with the Gradle Kotlin DSL, pins them to the embedded Kotlin version,

  • adds the kotlin-stdlib-jdk8, kotlin-reflect and gradleKotlinDsl() dependencies to the compileOnly and testImplementation configurations,

  • and, configures the Kotlin compiler with the same set of Kotlin compiler settings that is used for Gradle Kotlin DSL scripts.

The kotlin-dsl plugin enables experimental Kotlin compiler features. See the Kotlin compiler arguments section below for more information.

By default, the kotlin-dsl plugin warns about using experimental features of the Kotlin compiler. You can silence the warning by setting the experimentalWarning property of the kotlinDslPluginOptions extension to false as follows:

buildSrc/build.gradle.kts
plugins {
    `kotlin-dsl`
}

kotlinDslPluginOptions {
    experimentalWarning.set(false)
}

Kotlin compiler arguments

These are the Kotlin compiler arguments used for compiling Gradle Kotlin DSL scripts and Kotlin sources and scripts in a project that has the kotlin-dsl plugin applied:

-jvm-target=1.8

Sets the target version of the generated JVM bytecode to 1.8.

-Xjsr305=strict

Sets up Kotlin’s Java interoperability to strictly follow JSR-305 annotations for increased null safety. See Calling Java code from Kotlin in the Kotlin documentation for more information.

-XX:NewInference

Enables the experimental Kotlin compiler inference engine (required for SAM conversion for Kotlin functions).

-XX:SamConversionForKotlinFunctions

Enables SAM (Single Abstract Method) conversion for Kotlin functions in order to allow Kotlin build logic to expose and consume org.gradle.api.Action<T> based APIs. Such APIs can then be used uniformly from both the Kotlin and Groovy DSLs.

As an example, given the following hypothetical Kotlin function with a Java SAM parameter type:

fun kotlinFunctionWithJavaSam(action: org.gradle.api.Action<Any>) = TODO()

SAM conversion for Kotlin functions enables the following usage of the function:

kotlinFunctionWithJavaSam {
    // ...
}

Without SAM conversion for Kotlin functions one would have to explicitly convert the passed lambda:

kotlinFunctionWithJavaSam(Action {
    // ...
})