Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 36 ยท Performance and Migration

Migrating Groovy to Kotlin DSL and Upgrading Gradle Safely

Convert Groovy build scripts to the Kotlin DSL file by file, learn the syntax differences, then upgrade Gradle safely with the wrapper, deprecation warnings and release notes.

Gradle supports two build languages: Groovy (build.gradle) and Kotlin (build.gradle.kts). Kotlin is the default for new projects because the IDE can complete, navigate and refactor it with real types. Existing Groovy builds work fine and can stay, but many teams migrate gradually. Upgrading Gradle itself is the other routine chore, and it is much easier when you do it often and in small steps.

This lesson shows the syntax differences, a safe file-by-file migration order, and an upgrade procedure with the wrapper. It builds on the performance lesson and the Maven migration.

Gradle cannot run on this site; scripts are read-only. The Java stand-ins at the end convert simple Groovy dependency lines and compare Gradle versions, and run on Piston.

Syntax differences at a glance

Idea Groovy DSL Kotlin DSL
File name build.gradle build.gradle.kts
Strings 'single' or "double" "double" only
Method call implementation 'a:b:1' implementation("a:b:1")
Assignment version = '1.0' or version '1.0' version = "1.0"
Plugin block id 'java' id("java") or `java` / java
Boolean property enabled true isEnabled = true
Named task config test { useJUnitPlatform() } tasks.test { useJUnitPlatform() }
Look up a task tasks.named('test') tasks.named<Test>("test")
Variables def x = 1 val x = 1
Lists ['a', 'b'] listOf("a", "b")
Maps [a: 1] mapOf("a" to 1)
Closures doLast { println it } doLast { println(it) } (typed lambda)
Source set sourceSets { main { java.srcDirs = ['x'] } } sourceSets { main { java.srcDirs("x") } }

Side by side:

GROOVY
plugins {
    id 'java-library'
    id 'maven-publish'
}

group = 'com.example'
version = '1.0.0'

repositories {
    mavenCentral()
}

dependencies {
    api 'org.apache.commons:commons-lang3:3.17.0'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.11.4'
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = 'UTF-8'
}

test {
    useJUnitPlatform()
}
Kotlin
plugins {
    `java-library`
    `maven-publish`
}

group = "com.example"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    api("org.apache.commons:commons-lang3:3.17.0")
    testImplementation("org.junit.jupiter:junit-jupiter:5.11.4")
}

tasks.withType<JavaCompile>().configureEach {
    options.encoding = "UTF-8"
}

tasks.test {
    useJUnitPlatform()
}

Why bother? In Kotlin you get compile-time errors, jump-to-definition into Gradle APIs, and refactoring. The costs are slightly slower first-time script compilation (cached afterwards), a stricter syntax, and fewer old online examples, which are mostly Groovy.

Mixing is allowed

Each project can use its own language, and a settings.gradle.kts can sit next to build.gradle files. This makes a gradual move easy:

  1. Convert settings.gradle and the root build script.
  2. Convert convention plugins (they become precompiled .gradle.kts scripts in build-logic).
  3. Convert leaf projects one by one, running ./gradlew build after each.
  4. Remove leftover Groovy-only idioms.

Convert small things first and commit often, so a bisect can find a mistake.

Typical gotchas

  • Boolean properties get an is prefix in Kotlin: isEnabled, isTransitive, isFailOnError.
  • Dynamic properties (ext.foo = 1) become extra["foo"] = 1 or, better, typed val values and gradle.properties.
  • Map notation compile group: 'x', name: 'y' becomes implementation(group = "x", name = "y", version = "1").
  • Configurations created in the script: use val myConfig by configurations.creating.
  • Accessors such as implementation are generated only for applied plugins from the plugins {} block. Plugins applied with the legacy apply need "implementation"(...) string notation.
  • Groovy's it and implicit delegates are not available; Kotlin lambdas use it or this according to the DSL type, which the IDE shows.
Java Stand-in: converting Groovy dependency lines to Kotlin DSL

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 IO.readln() or a Scanner), it gets the next line from this box.

The last line is the typical case where an automatic converter gives up: more unusual forms deserve a human look.

Upgrading Gradle with the wrapper

Never upgrade by installing a new Gradle system-wide. The wrapper pins the version per project; upgrading means changing that pin:

TEXT
./gradlew wrapper --gradle-version 9.0.0 --distribution-type bin
./gradlew --version

This edits gradle/wrapper/gradle-wrapper.properties. Run the command twice after changing: the first run downloads and starts the new version, the second updates the wrapper scripts and jar themselves. Commit the changed files.

A safe upgrade procedure

  1. Build on the current version first with --warning-mode=all and fix deprecations:

    TEXT
    ./gradlew build --warning-mode=all
    

    Warnings say, for example, The Foo.bar property has been deprecated... scheduled to be removed in Gradle 10.

  2. Read the upgrade guide for your target version in the Gradle documentation; it lists breaking changes per major version.

  3. Upgrade one major version at a time (7 to 8, then 8 to 9), not 6 to 9 directly.

  4. Update plugins that the guide or errors mention (Kotlin, Android, Spring Boot, Shadow); old plugin versions often break on new Gradle.

  5. Run the full ./gradlew build, then test the published artifacts and CI.

  6. Turn on org.gradle.warning.mode=fail in CI later to prevent new deprecations from creeping in.

Verify the wrapper's integrity: the gradle-wrapper.jar checksum is published, and the distributionSha256Sum property in gradle-wrapper.properties makes Gradle check the downloaded distribution.

TEXT
distributionUrl=https\://services.gradle.org/distributions/gradle-9.0.0-bin.zip
distributionSha256Sum=<value from the Gradle release page>
Java Stand-in: is my Gradle version supported by this plugin?

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 IO.readln() or a Scanner), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How is the Groovy line implementation 'a:b:1' written in Kotlin DSL?

    Kotlin needs parentheses and double-quoted strings.
  2. 2. What replaces Groovy's boolean property syntax enabled true in Kotlin?

    Kotlin exposes boolean properties with an is prefix, for example isEnabled.
  3. 3. What is the safest way to move a big build from Groovy to Kotlin?

    Both languages can coexist, so small steps with a build after each keep risk low.
  4. 4. Why upgrade one major Gradle version at a time?

    Fixing deprecations on the current version and then moving one major at a time isolates problems.

Summary

  • Kotlin DSL gives type-safe, IDE-friendly scripts; Groovy still works and both can be mixed.
  • Learn the main syntax differences: parentheses, double quotes, is prefix, tasks.test, val.
  • Migrate settings, convention plugins and the root first, then leaf projects, building after each step.
  • Upgrade with the wrapper, fix --warning-mode=all messages first, and go one major version at a time.
  • Pin the distribution checksum for supply-chain safety.

Next: Project: a multi-module Java application