Gradle: Kotlin DSL, toolchains and tasks

Gradle is a build tool that models a build as a graph of tasks. A build script, build.gradle.kts in Gradle’s Kotlin DSL, applies plugins that add tasks: the java plugin adds compileJava, test, jar and build, and asking for build runs every task it depends on, in order. Gradle skips a task whose inputs and outputs have not changed since its last run, which keeps repeated builds fast. A toolchain names the Java version that compiles and tests the code, separately from the JDK that runs Gradle itself, and the wrapper, gradlew, fixes the Gradle version for everyone who builds the project. Android apps are built with Gradle, and so are many large Java projects.

This lesson ports the Maven exercise pack, an invoice library with four JUnit tests, to Gradle 9.7.1. Gradle runs on Java 21 here, while the toolchain compiles and tests with Eclipse Temurin 25.0.4.1. Gradle 9.8.1 is the newest release; the wrapper section shows how a project moves to it.

Maven and Gradle, side by side

The scope row follows Gradle’s guide to migrating from Maven, which maps each scope to the configuration that replaces it.

The build script

// The build's name, and the projects it contains: here only the root project.
rootProject.name = "invoice-tools"

// The exercise pack built with Gradle's Kotlin DSL: the same sources and tests as the Maven version.
plugins {
    // Adds the tasks that compile, test and package Java code (compileJava, test, jar, build ...).
    java
}

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

java {
    // Compile, test and run with a Java 25 toolchain, whatever JDK runs Gradle itself.
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // The JUnit BOM fixes the versions of every JUnit artifact; the platform launcher runs the tests.
    testImplementation(platform("org.junit:junit-bom:6.1.3"))
    testImplementation("org.junit.jupiter:junit-jupiter")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

tasks.test {
    useJUnitPlatform()
    // Print each test's result in the build output.
    testLogging {
        events("passed", "skipped", "failed")
    }
}

# Where Gradle finds JDKs for toolchains: the folder named by the JDK_25 environment variable, and nowhere else, so
# the build uses the same JDK on every computer that sets it. Without these lines Gradle also searches the usual
# install locations.
org.gradle.java.installations.fromEnv=JDK_25
org.gradle.java.installations.auto-detect=false
org.gradle.java.installations.auto-download=false

The settings file names the build and its projects. The build script applies the java plugin, sets the coordinates, asks for a Java 25 toolchain and declares Maven Central as the repository. Its three test dependencies are the JUnit BOM, which fixes the version of every JUnit artifact, JUnit Jupiter, and the platform launcher that Gradle uses to start JUnit. The test block runs the tests on the JUnit Platform and prints each result. The gradle.properties lines tell Gradle to take its JDKs from the JDK_25 environment variable only, so the build finds the same JDK on every computer that sets it.

Tasks form a graph

from session import run

# Gradle runs on Java 21 (JAVA_HOME); the build's toolchain compiles and tests with Java 25. The first build of a
# project also compiles its Kotlin build script and downloads JUnit.
run(
    """
gradle --version | grep -E "^(Gradle|Launcher JVM|Daemon JVM)"
gradle build
ls build/libs build/test-results/test
""",
    folder="invoice-tools",
    show=("java", "gradle"),
    java_home="21",
)

# openjdk version "25.0.4.1" LTS · Gradle 9.7.1 · JAVA_HOME: Java 21.0.12
$ gradle --version | grep -E "^(Gradle|Launcher JVM|Daemon JVM)"
Gradle 9.7.1
Launcher JVM:  21.0.12.1 (Eclipse Adoptium 21.0.12.1+1-LTS)
Daemon JVM:    …/installs/java/temurin-21.0.12+101.0.LTS (no Daemon JVM specified, using current Java home)
$ gradle build
> Task :compileJava
> Task :processResources NO-SOURCE
> Task :classes
> Task :jar
> Task :assemble
> Task :compileTestJava
> Task :processTestResources NO-SOURCE
> Task :testClasses

> Task :test

InvoiceTest > rejectsAZeroQuantity() PASSED

InvoiceTest > totalsTheInvoice() PASSED

InvoiceTest > roundsTaxHalfUpToTwoPlaces() PASSED

InvoiceTest > addsTaxToEachLine() PASSED

> Task :check
> Task :build

BUILD SUCCESSFUL in …
4 actionable tasks: 4 executed
Consider enabling configuration cache to speed up this build: https://docs.gradle.org/9.7.1/userguide/configuration_cache_enabling.html
$ ls build/libs build/test-results/test
build/libs:
invoice-tools-1.0.0.jar

build/test-results/test:
binary
TEST-com.example.invoice.InvoiceTest.xml

Gradle itself ran on Java 21, as its launcher and daemon lines show, while the toolchain compiled and tested with Java 25. The build passed through 11 tasks in the graph’s order. Four of them did real work, compileJava, jar, compileTestJava and test, which is what “4 actionable tasks: 4 executed” counts; the others group tasks or had no sources, marked NO-SOURCE. The 4 tests are the Maven version’s tests, and they passed again. The JAR landed in build/libs and the test results in build/test-results/test, where Maven used target. The last line of the build suggests the configuration cache, which reuses the result of evaluating the build scripts in later builds.

The order came from the graph, not from the build script: the script never mentions compileTestJava, and Gradle still ran it after classes, because the test classes need the main classes to compile. Asking for a single task runs only the part of the graph it needs, so gradle jar compiles the main code and stops without running a test, and gradle tasks lists every task the plugins added.

Four ideas to know by name

• Kotlin DSL. build.gradle.kts is Kotlin code that the IDE checks as you type; the Groovy DSL, build.gradle, drives the same API.
• Toolchain. The JDK that compiles, tests and runs the code, chosen by Java version from the JDKs Gradle knows.
• Wrapper. gradlew, gradlew.bat and the gradle/wrapper folder, committed so that ./gradlew runs the project’s Gradle version.
• Up-to-date checks. A task that declares its inputs and outputs is skipped when neither has changed.

Once a project has the wrapper, every command in this lesson becomes ./gradlew followed by the same task names, which is the form a build server should use. Android projects use the same wrapper, tasks and Kotlin DSL through the Android Gradle plugin, so these four ideas carry over to Android builds.

Check yourself

Toolchains in depth: one JDK runs Gradle, another compiles and tests Pro: opens with a Pro, Premium or Ultimate pass

Up-to-date checks measured: what Gradle skips, and a task that declares its inputs Pro: opens with a Pro, Premium or Ultimate pass

From Maven to Gradle: the converted pack, what init missed, and identical test results Pro: opens with a Pro, Premium or Ultimate pass

Key takeaways

• A Gradle build is a graph of tasks; build ran 11 tasks, 4 of which did real work.
• The toolchain decides which Java compiles and tests the code, whatever JDK runs Gradle itself.
• Maven scopes become configurations: implementation, compileOnly, runtimeOnly and testImplementation.
• Commit the wrapper so that everyone runs the same Gradle version with ./gradlew.