Gradle KTS – co to jest, Kotlin DSL dla Gradle i składnia

Czym jest Gradle KTS?

Gradle KTS – to Kotlin DSL (Domain Specific Language), stanowiący alternatywę dla Groovy do pisania plików konfiguracyjnych Gradle. Zamiast składni Groovy programiści używają Kotlin – języka o silnym typowaniu, który sprawdza poprawność konfiguracji na etapie kompilacji. KTS został po raz pierwszy wprowadzony w Gradle 5.0 w 2018 roku jako funkcja eksperymentalna i osiągnął stabilność w Gradle 6.0.

Głównym celem KTS jest wyeliminowanie wad Groovy w skryptach build. Groovy – to język z dynamicznym typowaniem, w którym błędy konfiguracji ujawniają się dopiero w runtime podczas wykonywania zadania. KTS pozwala wykryć te same błędy na etapie edycji kodu dzięki statycznemu typowaniu Kotlin. Dodatkowo KTS zapewnia dostęp do API Gradle z pełną dokumentacją typów, co znacznie ułatwia naukę i używanie złożonych bloków konfiguracyjnych.

Ekologia KTS jest wspierana przez wszystkie główne narzędzia: Android Studio, IntelliJ IDEA, VS Code z wtyczką Kotlin oraz Gradle Build Tool. Wszystkie nowoczesne wtyczki (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) udostępniają przyjazny dla Kotlin API z jawnymi typami, co czyni KTS preferowanym wyborem dla nowych projektów.

Jak działa Gradle KTS

Gradle KTS wykorzystuje kompilator Kotlin do przetwarzania plików .gradle.kts. Gradle rozpoznaje rozszerzenie i przekazuje skrypty do silnika skryptowego Kotlin, który kompiluje je do klas. Te klasy są następnie wykonywane przez Gradle w celu zbudowania modelu projektu. Kluczowa różnica w stosunku do Groovy: skrypty KTS są kompilowane z wyprzedzeniem, a nie interpretowane dynamicznie, co pozwala wykrywać błędy przed rozpoczęciem wykonywania zadań.

Architektura KTS opiera się na kotlin-scripting. Każdy plik .gradle.kts to skrypt Kotlin z niejawnymi importami API Gradle. Programista może używać dowolnych konstrukcji Kotlin: funkcji extension, lambd, klas data, a nawet deklarować funkcje pomocnicze wewnątrz skryptu build. Gradle udostępnia zestaw funkcji extension do typowanej konfiguracji bloków: dependencies, android, kotlin i innych.

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

Konwersja typów w KTS

Jedną z kluczowych różnic między KTS a Groovy jest praca z typami. W Groovy wszystkie konfiguracje przyjmują Object, w KTS – konkretne typy Kotlin. Na przykład compileSdk przyjmuje Int, a nie string. Wyklucza to błędy związane z niewłaściwym typem: w Groovy compileSdk 34 i compileSdk „34” działają tak samo, w KTS tylko pierwszy wariant. Taka ścisłość czyni konfigurację bardziej przewidywalną i udokumentowaną.

Gradle KTS vs Groovy: porównanie

Groovy był oryginalnym DSL dla Gradle i pozostaje w pełni wspierany. Jednak KTS oferuje szereg zalet, które czynią go zalecanym dla nowych projektów. Statyczne typowanie, lepsza wydajność edycji w IDE i bardziej rygorystyczna składnia – to główne powody przejścia na KTS. Przy tym Groovy zachowuje przewagę w zwięzłości dla prostych konfiguracji.

Wydajność budowania na KTS i Groovy jest praktycznie identyczna po kompilacji skryptów. Skrypty KTS kompilują się dłużej przy pierwszym uruchomieniu lub po wyczyszczeniu cache, ale kolejne budowania działają z tą samą prędkością co skrypty Groovy. Gradle cache'uje skompilowane skrypty KTS w katalogu build, więc ponowna kompilacja następuje tylko przy zmianie skryptu.

Wybór między KTS a Groovy w 2026 roku jest oczywisty: dla nowych projektów – KTS. Google, JetBrains i Gradle zalecają KTS dla wszystkich nowych projektów. Groovy pozostaje aktualny dla wsparcia projektów legacy, gdzie migracja jest niecelowa ze względu na objętość konfiguracji lub specyficzne wtyczki niekompatybilne z KTS.

Przykłady kodu: skrypty build w KTS

Rozpatrzmy typowe bloki konfiguracyjne w KTS dla Android, Kotlin Multiplatform i Compose Multiplatform. Projekt Android z KTS wymaga jawnego określenia typów w konfiguracji buildTypes i productFlavors. Poniższy przykład demonstruje konfigurację aplikacji z dwoma flavour'ami.

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

Dla Kotlin Multiplatform KTS jest obowiązkowy – Groovy nie obsługuje poprawnie konfiguracji modułów wieloplatformowych. Konfiguracja modułu KMM obejmuje ustawienie platform docelowych i source set'ów. Poniższy przykład pokazuje konfigurację modułu shared z iOS i 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")
        }
    }
}

Funkcje pomocnicze i zadania niestandardowe

KTS pozwala deklarować pomocnicze funkcje Kotlin wewnątrz skryptu build. Jest to szczególnie wygodne dla powtarzalnych konfiguracji, takich jak signing configs czy zarządzanie wersjami. Dzięki statycznemu typowaniu takie funkcje można wywoływać z weryfikacją parametrów na etapie kompilacji, co eliminuje błędy w konfiguracjach signing przed publikacją w 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")
            }
        }
    }
}

// Użycie w build.gradle.kts
configureSigning()

Migracja z Groovy na KTS

Migracja z Groovy na KTS – to proces, który można wykonywać stopniowo. Gradle obsługuje projekty mieszane, w których część modułów używa Groovy (build.gradle), a część – KTS (build.gradle.kts). settings.gradle i root build.gradle mogą być przetłumaczone jako pierwsze, ponieważ nie zależą od wtyczek modułów. Google zaleca rozpoczęcie migracji od settings.gradle.kts, następnie główny build.gradle.kts, a dopiero potem moduły.

Główne kroki migracji obejmują: zastąpienie składni closures lambdami, dodanie znaków = dla przypisań, zastąpienie kluczy stringowych typowanymi stałymi i jawne typowanie zmiennych. Android Studio zapewnia automatyczną konwersję Groovy → KTS dla prostych bloków, ale złożone konfiguracje z zagnieżdżonymi closures wymagają ręcznego przepisywania.

Typowe problemy przy migracji obejmują niejawne wywołania metod Groovy, które nie mają odpowiednika w Kotlin, oraz wtyczki, które nie udostępniają przyjaznego dla Kotlin API. Do rozwiązania pierwszego problemu Gradle zapewnia zgodność przez withGroovyBuilder – mechanizm, który pozwala wywoływać metody Groovy z KTS. Dla drugiego – należy poczekać na aktualizację wtyczki lub użyć jej w module Groovy do pełnej migracji.

Gradle KTS dla Kotlin Multiplatform

Kotlin Multiplatform – to główny projekt, w którym KTS jest obowiązkowym wymaganiem. Wtyczka kotlin multiplatform udostępnia rozszerzenia do konfiguracji platform docelowych, source set'ów i binariów framework, które są dostępne tylko przez Kotlin DSL. Groovy nie obsługuje poprawnie konfiguracji wieloplatformowej, dlatego projekty KMM używają wyłącznie KTS.

Konfiguracja KMM w KTS obejmuje niestandardowe bloki: kotlin.target do określania platform, kotlin.sourceSets do organizacji kodu wspólnego i platformowego, kotlin.cocoapods do integracji z CocoaPods oraz kotlin.jvmToolchain do wyboru JDK. Każdy blok ma ściśle typowane API z autouzupełnianiem w Android Studio, co jest szczególnie cenne dla złożonej konfiguracji projektu KMM z wieloma platformami.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

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

Dzięki statycznemu typowaniu KTS programiści KMM otrzymują autouzupełnianie dla source set'ów i zależności, weryfikację typów konfiguracji framework oraz możliwość refaktoryzacji nazw platformowych. KTS ułatwia także debugowanie: błędy w konfiguracji KMM wyświetlane są jako błędy kompilacji Kotlin z zrozumiałymi komunikatami, w przeciwieństwie do Groovy, gdzie błędy mogły być ukryte do momentu wykonania zadania Gradle.