Gradle KTS — co to je, Kotlin DSL pro Gradle a syntaxe

Co je Gradle KTS?

Gradle KTS — je Kotlin DSL (Domain Specific Language), který poskytuje alternativu ke Groovy pro psaní konfiguračních souborů Gradle. Místo syntaxe Groovy vývojáři používají Kotlin — přísně typovaný jazyk, který kontroluje správnost konfigurace ve fázi kompilace. KTS byl poprvé představen v Gradle 5.0 v roce 2018 jako experimentální funkce a dosáhl stability v Gradle 6.0.

Hlavním cílem KTS je odstranit nedostatky Groovy v build skriptech. Groovy — dynamicky typovaný jazyk, ve kterém se chyby konfigurace projevují až za běhu při provádění úkolů. KTS umožňuje detekovat stejné chyby ve fázi úpravy kódu díky statickému typování Kotlin. Kromě toho KTS poskytuje přístup k API Gradle s úplnou dokumentací typů, což výrazně usnadňuje učení a používání složitých konfiguračních bloků.

Ekostystém KTS je podporován všemi hlavními nástroji: Android Studio, IntelliJ IDEA, VS Code s pluginem Kotlin a Gradle Build Tool. Všechny moderní pluginy (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) poskytují Kotlin-přátelské API s explicitními typy, což činí KTS preferovanou volbou pro nové projekty.

Jak funguje Gradle KTS

Gradle KTS používá kompilátor Kotlin pro zpracování souborů .gradle.kts. Gradle rozpozná příponu a předá skripty skriptovacímu enginu Kotlin, který je zkompiluje do tříd. Tyto třídy jsou poté spuštěny Gradlem pro sestavení modelu projektu. Klíčový rozdíl oproti Groovy: skripty KTS jsou kompilovány předem, nejsou dynamicky interpretovány, což umožňuje odhalit chyby před zahájením provádění úkolů.

Architektura KTS je založena na kotlin-scripting. Každý soubor .gradle.kts je skript Kotlin s implicitními importy API Gradle. Vývojář může používat libovolné konstrukce Kotlin: extension funkce, lambdy, data třídy a dokonce deklarovat pomocné funkce uvnitř build skriptu. Gradle poskytuje sadu extension funkcí pro typovanou konfiguraci bloků: dependencies, android, kotlin a další.

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")
}

Konverze typů v KTS

Jedním z klíčových rozdílů mezi KTS a Groovy je práce s typy. V Groovy všechny konfigurace přijímají Object, v KTS — konkrétní Kotlin typy. Například compileSdk přijímá Int, ne řetězec. To vylučuje chyby související s nesprávným typem: v Groovy compileSdk 34 a compileSdk „34“ fungují stejně, v KTS pouze první varianta. Taková přísnost činí konfiguraci předvídatelnější a zdokumentovanější.

Gradle KTS vs Groovy: srovnání

Groovy byl původní DSL pro Gradle a zůstává plně podporován. KTS však nabízí řadu výhod, které jej činí doporučeným pro nové projekty. Statické typování, lepší výkon úprav v IDE a přísnější syntaxe — hlavní důvody přechodu na KTS. Groovy si přitom zachovává výhodu stručnosti pro jednoduché konfigurace.

Výkon sestavování na KTS a Groovy je po kompilaci skriptů prakticky identický. Skripty KTS se kompilují déle při prvním spuštění nebo po vymazání mezipaměti, ale následná sestavení pracují stejnou rychlostí jako skripty Groovy. Gradle ukládá zkompilované skripty KTS do mezipaměti v adresáři build, takže rekompilace probíhá pouze při změně skriptu.

Volba mezi KTS a Groovy v roce 2026 je jasná: pro nové projekty — KTS. Google, JetBrains a Gradle doporučují KTS pro všechny nové projekty. Groovy zůstává relevantní pro podporu starších projektů, kde migrace není účelná kvůli objemu konfigurací nebo specifickým pluginům nekompatibilním s KTS.

Příklady kódu: build skripty v KTS

Podívejme se na typické konfigurační bloky v KTS pro Android, Kotlin Multiplatform a Compose Multiplatform. Android projekt s KTS vyžaduje explicitní uvedení typů v konfiguraci buildTypes a productFlavors. Níže uvedený příklad ukazuje konfiguraci aplikace se dvěma flavoury.

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"
        }
    }
}

Pro Kotlin Multiplatform je KTS povinný — Groovy nepodporuje správně konfiguraci víceplatformních modulů. Konfigurace modulu KMM zahrnuje nastavení cílových platforem a source setů. Níže uvedený příklad ukazuje konfiguraci sdíleného modulu s iOS a 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")
        }
    }
}

Pomocné funkce a vlastní úkoly

KTS umožňuje deklarovat pomocné funkce Kotlin uvnitř build skriptu. To je zvláště vhodné pro opakující se konfigurace, jako jsou signing configs nebo správa verzí. Díky statickému typování lze takové funkce volat s kontrolou parametrů ve fázi kompilace, což vylučuje chyby v signing konfiguracích před publikováním do Google Play.

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")
            }
        }
    }
}

// Použití v build.gradle.kts
configureSigning()

Migrace z Groovy na KTS

Migrace z Groovy na KTS — proces, který lze provádět postupně. Gradle podporuje smíšené projekty, kde část modulů používá Groovy (build.gradle) a část KTS (build.gradle.kts). settings.gradle a root build.gradle mohou být převedeny první, protože nejsou závislé na pluginech modulů. Google doporučuje začít migraci pomocí settings.gradle.kts, poté root build.gradle.kts a až poté moduly.

Hlavní kroky migrace zahrnují: nahrazení syntaxe closures lambdami, přidání znaků = pro přiřazení, nahrazení řetězcových klíčů typovanými konstantami a explicitní typování proměnných. Android Studio poskytuje automatickou konverzi Groovy → KTS pro jednoduché bloky, ale složité konfigurace s vnořenými closures vyžadují ruční přepsání.

Typické problémy při migraci zahrnují implicitní volání metod Groovy, které nemají ekvivalent v Kotlin, a pluginy, které neposkytují Kotlin-přátelské API. Pro řešení prvního problému poskytuje Gradle kompatibilitu prostřednictvím withGroovyBuilder — mechanismu, který umožňuje volat metody Groovy z KTS. Pro druhý — je třeba počkat na aktualizaci pluginu nebo jej použít v modulu Groovy do úplné migrace.

Gradle KTS pro Kotlin Multiplatform

Kotlin Multiplatform — hlavní projekt, ve kterém je KTS povinným požadavkem. Plugin kotlin multiplatform poskytuje rozšíření pro konfiguraci cílových platforem, source setů a framework binárních souborů, která jsou dostupná pouze přes Kotlin DSL. Groovy nepodporuje správně víceplatformní konfiguraci, proto projekty KMM používají výhradně KTS.

Konfigurace KMM v KTS zahrnuje nestandardní bloky: kotlin.target pro určení platforem, kotlin.sourceSets pro organizaci společného a platformově specifického kódu, kotlin.cocoapods pro integraci s CocoaPods a kotlin.jvmToolchain pro výběr JDK. Každý blok má přísně typované API s automatickým doplňováním v Android Studiu, což je zvláště cenné pro složitou konfiguraci projektu KMM s více platformami.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

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

Díky statickému typování KTS získávají vývojáři KMM automatické doplňování pro source sety a závislosti, kontrolu typů konfigurace frameworku a možnost refaktorování názvů platforem. KTS také usnadňuje ladění: chyby v konfiguraci KMM se zobrazují jako chyby kompilace Kotlin se srozumitelnými zprávami, na rozdíl od Groovy, kde chyby mohly být skryty až do spuštění úkolu Gradle.