Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Build Scripts: Groovy and Kotlin DSL

Kotlin DSL Basics: build.gradle.kts, Type Safety and Migration

Learn the Gradle Kotlin DSL: lambdas with receivers, type-safe accessors, tasks.named and register, and how to translate a Groovy build file to build.gradle.kts.

The Kotlin DSL writes your build in Kotlin, in files named build.gradle.kts and settings.gradle.kts. It is the default when you run gradle init today and what the official documentation uses first. Its big advantage is static typing: your IDE can autocomplete every block, jump to definitions and flag mistakes before you run the build. The price is a slightly slower first configuration, because the script is compiled.

The Gradle snippets are read-only, but Kotlin runs on this site, so the key mechanism (a lambda with a receiver) is shown with runnable Kotlin stand-ins.

Same build, two DSLs

Groovy (build.gradle):

GROOVY
plugins {
    id 'java'
    id 'application'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.google.guava:guava:33.4.0-jre'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.11.4'
}

application {
    mainClass = 'com.example.App'
}

tasks.register('hello') {
    doLast { println 'hi' }
}

Kotlin (build.gradle.kts):

Kotlin
plugins {
    java
    application
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("com.google.guava:guava:33.4.0-jre")
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
}

application {
    mainClass = "com.example.App"
}

tasks.register("hello") {
    doLast { println("hi") }
}

Translation cheat sheet

Groovy Kotlin
'single' or "double" strings always "double" (single quotes mean a Char)
implementation 'x' implementation("x")
id 'java' java (core plugin accessor) or id("java")
id 'org.springframework.boot' version '3.4.0' id("org.springframework.boot") version "3.4.0"
mainClass = 'x' mainClass = "x" (a property assignment)
tasks.register('t') { } tasks.register("t") { }
tasks.named('test') { } tasks.named<Test>("test") { }
def x = 1 val x = 1
ext.foo = 1 extra["foo"] = 1
[a: 1], ['a','b'] mapOf("a" to 1), listOf("a", "b")
println "x" println("x")

Type-safe accessors

When you apply a plugin in the plugins {} block, the Kotlin DSL generates accessors for what it adds: that is why application { }, java { }, testImplementation(...) and sourceSets are available as ordinary names with autocompletion. For things the accessor generator cannot see (for example a plugin applied conditionally or in buildSrc), use the generic form:

Kotlin
val implementation by configurations     // delegated property, rarely needed
configure<JavaPluginExtension> {
    toolchain.languageVersion = JavaLanguageVersion.of(21)
}
dependencies {
    add("implementation", "com.google.guava:guava:33.4.0-jre")
}

If you are copying a snippet that fails with "unresolved reference", check that the plugin is declared in plugins {} first.

Lambdas with receivers

Every Kotlin DSL block is a lambda with a receiver: dependencies { ... } is a function that takes a lambda of type DependencyHandlerScope.() -> Unit. Inside the braces, this is a DependencyHandlerScope, so implementation("...") is simply this.implementation("..."). It is the same idea as Groovy's closure delegate, only statically checked.

Stand-in: a type-safe builder in Kotlin

The Kotlin below is not Gradle, but it is the same mechanism. dependencies { } takes a lambda whose this is a Dependencies object.

Kotlin Stand-in: lambdas with receivers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Try typing implementatoin("x") in the editor: the compiler rejects it. That early feedback is what Kotlin gives you.

Assigning properties: = and .set()

Gradle's lazy properties (Property<T>) can be assigned with = in the Kotlin DSL (since Gradle 8.2):

Kotlin
application {
    mainClass = "com.example.App"      // Property<String>
}
tasks.jar {
    archiveBaseName = "shop-api"       // also works
}

Older scripts call .set("..."); both are equivalent. For collections use .add(...), .addAll(...) or +=-like helpers on the provider.

Referencing tasks

Kotlin
tasks.test { useJUnitPlatform() }                 // accessor for a known task
tasks.named<Test>("test") { useJUnitPlatform() }  // lazy lookup by name and type
tasks.withType<Test>().configureEach { useJUnitPlatform() }

val docs by tasks.registering(Copy::class) {     // delegate: creates a val for the task
    from("src/docs")
    into(layout.buildDirectory.dir("docs"))
}
tasks.named("build") { dependsOn(docs) }

by tasks.registering gives you a TaskProvider in a val, which you can pass to dependsOn and use safely in other tasks.

Stand-in: typed task configuration

A second stand-in shows why named<Test> has a type argument: the lambda's receiver is that exact type, so only its members are available.

Kotlin Stand-in: typed lookups

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with readln()), it gets the next line from this box.

Mixing Groovy and Kotlin, and migrating

Groovy and Kotlin build files can live in the same multi-project build; each project chooses its own. To migrate a project:

  1. Rename build.gradle to build.gradle.kts and convert the syntax with the cheat sheet above.
  2. Fix strings (double quotes), parentheses on calls and named<Type> lookups.
  3. Replace ext with gradle.properties, a version catalog or extra.
  4. Run ./gradlew help and fix errors one by one; the IDE's error list is accurate.
  5. Convert settings.gradle last, or leave it in Groovy.

The performance chapter covers the cost of script compilation and how to reduce it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the main advantage of the Kotlin DSL over Groovy?

    Kotlin is statically typed, so IDEs can complete and verify names and types before the build runs.
  2. 2. How do you write the Groovy line implementation 'x:y:1.0' in Kotlin?

    Kotlin needs parentheses for calls and double quotes for strings.
  3. 3. What type of lambda do Kotlin DSL blocks such as dependencies { } use?

    Inside the block, this refers to the receiver (for example the dependency handler), so its functions are called without a prefix.
  4. 4. Why use tasks.named<Test>("test") instead of tasks.named("test")?

    With the type, members like useJUnitPlatform() and maxHeapSize are available and checked at compile time.

Summary

  • Kotlin DSL files end in .gradle.kts; strings use double quotes and calls use parentheses.
  • Blocks are lambdas with receivers, the typed counterpart of Groovy closures.
  • Plugin accessors (application { }, testImplementation) appear after the plugin is in plugins {}.
  • Use tasks.named<T>, tasks.register and tasks.withType<T>().configureEach for lazy, typed task configuration.
  • Assign properties with = in modern Gradle.
  • Migrate file by file; Groovy and Kotlin scripts can coexist.

Next: Properties, gradle.properties and Extra Values