# Gradle Kotlin DSL

💡 | 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 {
          // ...
      })