Gradle KTS — wat is het, Kotlin DSL voor Gradle en syntax

Wat is Gradle KTS?

Gradle KTS — is Kotlin DSL (Domain Specific Language), een alternatief voor Groovy voor het schrijven van Gradle-configuratiebestanden. In plaats van Groovy-syntax gebruiken ontwikkelaars Kotlin — een sterk getypeerde taal die de juistheid van de configuratie tijdens compilatie controleert. KTS werd voor het eerst geïntroduceerd in Gradle 5.0 in 2018 als experimentele functie en bereikte stabiliteit in Gradle 6.0.

Het hoofddoel van KTS is het elimineren van de nadelen van Groovy in build-scripts. Groovy — een dynamisch getypeerde taal waarin configuratiefouten pas tijdens runtime verschijnen bij het uitvoeren van taken. KTS maakt het mogelijk dezelfde fouten te detecteren tijdens het bewerken van code dankzij de statische typering van Kotlin. Bovendien biedt KTS toegang tot de Gradle API met volledige typedocumentatie, wat het leren en gebruiken van complexe configuratieblokken aanzienlijk vereenvoudigt.

Het KTS-ecosysteem wordt ondersteund door alle belangrijke tools: Android Studio, IntelliJ IDEA, VS Code met Kotlin-plugin en Gradle Build Tool. Alle moderne plugins (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) bieden een Kotlin-vriendelijke API met expliciete types, waardoor KTS de voorkeurskeuze is voor nieuwe projecten.

Hoe Gradle KTS werkt

Gradle KTS gebruikt de Kotlin-compiler voor het verwerken van .gradle.kts-bestanden. Gradle herkent de extensie en geeft de scripts door aan de Kotlin-scriptengine, die ze compileert naar klassen. Deze klassen worden vervolgens door Gradle uitgevoerd om het projectmodel te bouwen. Het belangrijkste verschil met Groovy: KTS-scripts worden vooraf gecompileerd in plaats van dynamisch geïnterpreteerd, waardoor fouten kunnen worden gedetecteerd voordat taken worden uitgevoerd.

De architectuur van KTS is gebaseerd op kotlin-scripting. Elk .gradle.kts-bestand is een Kotlin-script met impliciete imports van de Gradle API. De ontwikkelaar kan alle Kotlin-constructies gebruiken: extensiefuncties, lambda's, data-klassen en zelfs hulpfuncties declareren binnen het build-script. Gradle biedt een set extensiefuncties voor getypeerde configuratie van blokken: dependencies, android, kotlin en andere.

plugins {
    id("com.android.application") version "8.4.0"
    kotlin("android") version "2.0.21"
}

android {
    namespace = "com.itsectr.app"
    compileSdk = 34

    defaultConfig {
        applicationId = "com.itsectr.app"
        minSdk = 26
        targetSdk = 34
        versionCode = 1
        versionName = "1.0.0"
    }
}

dependencies {
    implementation(platform("androidx.compose:compose-bom:2024.06.00"))
    implementation("androidx.compose.ui:ui")
    implementation("androidx.core:core-ktx:1.13.1")
}

Typeconversie in KTS

Een van de belangrijkste verschillen tussen KTS en Groovy is het werken met types. In Groovy accepteren alle configuraties Object, in KTS — concrete Kotlin-types. Bijvoorbeeld, compileSdk accepteert Int, geen string. Dit voorkomt fouten gerelateerd aan onjuiste types: in Groovy werken compileSdk 34 en compileSdk “34” hetzelfde, in KTS alleen de eerste variant. Deze nauwkeurigheid maakt de configuratie voorspelbaarder en beter gedocumenteerd.

Gradle KTS vs Groovy: vergelijking

Groovy was de oorspronkelijke DSL voor Gradle en blijft volledig ondersteund. KTS biedt echter een aantal voordelen die het aanbevolen maken voor nieuwe projecten. Statische typering, betere bewerkingsprestaties in de IDE en een striktere syntax — de belangrijkste redenen om over te stappen op KTS. Tegelijkertijd behoudt Groovy het voordeel van beknoptheid voor eenvoudige configuraties.

De bouwprestaties van KTS en Groovy zijn vrijwel identiek na compilatie van de scripts. KTS-scripts compileren langer bij de eerste start of na het wissen van de cache, maar volgende builds werken met dezelfde snelheid als Groovy-scripts. Gradle cached gecompileerde KTS-scripts in de build-directory, dus hercompilatie vindt alleen plaats bij wijziging van het script.

De keuze tussen KTS en Groovy in 2026 is duidelijk: voor nieuwe projecten — KTS. Google, JetBrains en Gradle bevelen KTS aan voor alle nieuwe projecten. Groovy blijft relevant voor ondersteuning van legacy-projecten waar migratie niet opportuun is vanwege de omvang van configuraties of specifieke plugins die incompatibel zijn met KTS.

Code voorbeelden: build-scripts in KTS

Laten we typische configuratieblokken in KTS bekijken voor Android, Kotlin Multiplatform en Compose Multiplatform. Android-project met KTS vereist expliciete type-aanduiding in de configuratie van buildTypes en productFlavors. Het onderstaande voorbeeld toont de configuratie van een app met twee flavours.

android {
    buildTypes {
        val release = getByName("release") {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        getByName("debug") {
            applicationIdSuffix = ".debug"
        }
    }

    flavorDimensions += "version"
    productFlavors {
        register("demo") {
            dimension = "version"
            versionNameSuffix = "-demo"
        }
        register("full") {
            dimension = "version"
        }
    }
}

Voor Kotlin Multiplatform is KTS verplicht — Groovy ondersteunt multi-platform moduleconfiguratie niet correct. De configuratie van een KMM-module omvat het instellen van doelplatforms en source sets. Het onderstaande voorbeeld toont de configuratie van een shared-module met iOS en Android.

kotlin {
    androidTarget {
        compilations.all {
            kotlinOptions {
                jvmTarget = "17"
            }
        }
    }

    listOf(
        iosX64(),
        iosArm64(),
        iosSimulatorArm64()
    ).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "Shared"
            isStatic = true
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
        }
        androidMain.dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.9.0")
        }
    }
}

Hulpfuncties en aangepaste taken

KTS maakt het mogelijk om hulp-Kotlin-functies te declareren binnen het build-script. Dit is vooral handig voor herhalende configuraties zoals signing configs of versiebeheer. Dankzij statische typering kunnen dergelijke functies worden aangeroepen met parametercontrole tijdens compilatie, wat fouten in signing-configuraties vóór publicatie naar Google Play voorkomt.

fun Project.configureSigning() {
    android {
        signingConfigs {
            register("release") {
                storeFile = file("release.keystore")
                storePassword = System.getenv("KEYSTORE_PASSWORD")
                keyAlias = System.getenv("KEY_ALIAS")
                keyPassword = System.getenv("KEY_PASSWORD")
            }
        }
    }
}

// Gebruik in build.gradle.kts
configureSigning()

Migratie van Groovy naar KTS

Migratie van Groovy naar KTS — een proces dat geleidelijk kan worden uitgevoerd. Gradle ondersteunt gemengde projecten waar een deel van de modules Groovy (build.gradle) gebruikt en een deel KTS (build.gradle.kts). settings.gradle en root build.gradle kunnen als eerste worden omgezet omdat ze niet afhankelijk zijn van module-plugins. Google beveelt aan om de migratie te beginnen met settings.gradle.kts, dan root build.gradle.kts, en pas daarna de modules.

De belangrijkste migratiestappen zijn: vervangen van closure-syntax door lambda's, toevoegen van = voor toewijzing, vervangen van string-sleutels door getypeerde constanten en expliciete typering van variabelen. Android Studio biedt automatische conversie van Groovy naar KTS voor eenvoudige blokken, maar complexe configuraties met geneste closures vereisen handmatig herschrijven.

Typische problemen bij migratie zijn impliciete aanroepen van Groovy-methoden die geen Kotlin-equivalent hebben en plugins die geen Kotlin-vriendelijke API bieden. Voor het eerste probleem biedt Gradle compatibiliteit via withGroovyBuilder — een mechanisme dat het mogelijk maakt Groovy-methoden vanuit KTS aan te roepen. Voor het tweede — wacht op een plugin-update of gebruik deze in de Groovy-module tot volledige migratie.

Gradle KTS voor Kotlin Multiplatform

Kotlin Multiplatform — het belangrijkste project waarin KTS een verplichte vereiste is. De kotlin multiplatform-plugin biedt extensies voor het configureren van doelplatforms, source sets en framework-binaires die alleen beschikbaar zijn via Kotlin DSL. Groovy ondersteunt multi-platformconfiguratie niet correct, daarom gebruiken KMM-projecten uitsluitend KTS.

KMM-configuratie in KTS omvat niet-standaard blokken: kotlin.target voor het specificeren van platforms, kotlin.sourceSets voor het organiseren van gedeelde en platformspecifieke code, kotlin.cocoapods voor integratie met CocoaPods en kotlin.jvmToolchain voor JDK-selectie. Elk blok heeft een strikt getypeerde API met automatische aanvulling in Android Studio, wat bijzonder waardevol is voor complexe KMM-projectconfiguratie met meerdere platforms.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

    cocoapods {
        summary = "Shared Kotlin module"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = false
        }
        pod("Alamofire") {
            version = "5.9"
        }
    }
}

Dankzij de statische typering van KTS krijgen KMM-ontwikkelaars automatische aanvulling voor source sets en afhankelijkheden, typecontrole van framework-configuratie en de mogelijkheid tot refactoring van platformnamen. KTS vereenvoudigt ook het debuggen: fouten in KMM-configuratie worden weergegeven als Kotlin-compilatiefouten met begrijpelijke meldingen, in tegenstelling tot Groovy waar fouten verborgen konden blijven tot het uitvoeren van een Gradle-taak.