Gradle KTS — ce este, Kotlin DSL pentru Gradle și sintaxa

Ce este Gradle KTS?

Gradle KTS — este Kotlin DSL (Domain Specific Language), care oferă o alternativă la Groovy pentru scrierea fișierelor de configurare Gradle. În loc de sintaxa Groovy, dezvoltatorii folosesc Kotlin — un limbaj puternic tipizat care verifică corectitudinea configurației în etapa de compilare. KTS a fost introdus pentru prima dată în Gradle 5.0 în 2018 ca funcție experimentală și a atins stabilitatea în Gradle 6.0.

Scopul principal al KTS este de a elimina deficiențele Groovy în scripturile build. Groovy — un limbaj cu tipizare dinamică, în care erorile de configurare apar doar în runtime la executarea task-urilor. KTS permite detectarea acelorași erori în etapa de editare a codului datorită tipizării statice a Kotlin. În plus, KTS oferă acces la API-ul Gradle cu documentație completă a tipurilor, ceea ce simplifică semnificativ învățarea și utilizarea blocurilor complexe de configurare.

Ecosistemul KTS este suportat de toate instrumentele principale: Android Studio, IntelliJ IDEA, VS Code cu pluginul Kotlin și Gradle Build Tool. Toate pluginurile moderne (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) oferă un API prietenos Kotlin cu tipuri explicite, ceea ce face din KTS alegerea preferată pentru proiectele noi.

Cum funcționează Gradle KTS

Gradle KTS folosește compilatorul Kotlin pentru procesarea fișierelor .gradle.kts. Gradle recunoaște extensia și transmite scripturile motorului de scripturi Kotlin, care le compilează în clase. Aceste clase sunt apoi executate de Gradle pentru construirea modelului proiectului. Diferența cheie față de Groovy: scripturile KTS sunt compilate în avans, nu interpretate dinamic, ceea ce permite detectarea erorilor înainte de începerea executării task-urilor.

Arhitectura KTS se bazează pe kotlin-scripting. Fiecare fișier .gradle.kts este un script Kotlin cu importuri implicite ale API-ului Gradle. Dezvoltatorul poate folosi orice construcții Kotlin: funcții extension, lambda, clase data și chiar declararea funcțiilor auxiliare în interiorul scriptului build. Gradle oferă un set de funcții extension pentru configurarea tipizată a blocurilor: dependencies, android, kotlin și altele.

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

Conversia tipurilor în KTS

Una dintre diferențele cheie dintre KTS și Groovy este lucrul cu tipurile. În Groovy, toate configurațiile primesc Object, în KTS — tipuri concrete Kotlin. De exemplu, compileSdk primește Int, nu un string. Acest lucru exclude erorile legate de tipul incorect: în Groovy compileSdk 34 și compileSdk „34” funcționează la fel, în KTS doar prima variantă. O astfel de rigurozitate face configurarea mai previzibilă și documentată.

Gradle KTS vs Groovy: comparație

Groovy a fost DSL-ul original pentru Gradle și rămâne complet suportat. Cu toate acestea, KTS oferă o serie de avantaje care îl fac recomandat pentru proiectele noi. Tipizarea statică, performanța mai bună de editare în IDE și sintaxa mai strictă — principalele motive pentru trecerea la KTS. În același timp, Groovy păstrează avantajul conciziei pentru configurații simple.

Performanța build-ului pe KTS și Groovy este practic identică după compilarea scripturilor. Scripturile KTS se compilează mai mult la prima lansare sau după curățarea cache-ului, dar build-urile ulterioare funcționează cu aceeași viteză ca scripturile Groovy. Gradle stochează în cache scripturile KTS compilate în directorul build, astfel că recompilarea are loc doar la modificarea scriptului.

Alegerea între KTS și Groovy în 2026 este evidentă: pentru proiecte noi — KTS. Google, JetBrains și Gradle recomandă KTS pentru toate proiectele noi. Groovy rămâne relevant pentru suportul proiectelor legacy, unde migrarea nu este oportună din cauza volumului de configurații sau a pluginurilor specifice incompatibile cu KTS.

Exemple de cod: scripturi build în KTS

Să examinăm blocurile tipice de configurare în KTS pentru Android, Kotlin Multiplatform și Compose Multiplatform. Proiectul Android cu KTS necesită specificarea explicită a tipurilor în configurarea buildTypes și productFlavors. Exemplul de mai jos demonstrează configurarea unei aplicații cu două flavour-uri.

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

Pentru Kotlin Multiplatform KTS este obligatoriu — Groovy nu suportă corect configurarea modulelor multi-platformă. Configurarea modulului KMM include setarea platformelor țintă și a source set-urilor. Exemplul de mai jos arată configurarea modulului shared cu 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")
        }
    }
}

Funcții auxiliare și task-uri personalizate

KTS permite declararea funcțiilor auxiliare Kotlin în interiorul scriptului build. Acest lucru este deosebit de convenabil pentru configurații repetitive, cum ar fi signing configs sau gestionarea versiunilor. Datorită tipizării statice, astfel de funcții pot fi apelate cu verificarea parametrilor în etapa de compilare, ceea ce exclude erorile în configurațiile de signing înainte de publicarea în 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")
            }
        }
    }
}

// Utilizare în build.gradle.kts
configureSigning()

Migrarea de la Groovy la KTS

Migrarea de la Groovy la KTS — un proces care poate fi realizat treptat. Gradle suportă proiecte mixte, unde o parte din module folosesc Groovy (build.gradle), iar o parte — KTS (build.gradle.kts). settings.gradle și root build.gradle pot fi traduse primele, deoarece nu depind de pluginurile modulelor. Google recomandă începerea migrării cu settings.gradle.kts, apoi root build.gradle.kts, și abia apoi modulele.

Pașii principali ai migrării includ: înlocuirea sintaxei closures cu lambda, adăugarea semnelor = pentru atribuire, înlocuirea cheilor string cu constante tipizate și tipizarea explicită a variabilelor. Android Studio oferă conversie automată Groovy → KTS pentru blocuri simple, dar configurațiile complexe cu closures imbricate necesită rescriere manuală.

Problemele tipice la migrare includ apelurile implicite ale metodelor Groovy care nu au echivalent Kotlin și pluginurile care nu oferă un API prietenos Kotlin. Pentru rezolvarea primei probleme, Gradle oferă compatibilitate prin withGroovyBuilder — un mecanism care permite apelarea metodelor Groovy din KTS. Pentru a doua — este necesar să așteptați actualizarea pluginului sau să îl folosiți în modulul Groovy până la migrarea completă.

Gradle KTS pentru Kotlin Multiplatform

Kotlin Multiplatform — proiectul principal în care KTS este o cerință obligatorie. Pluginul kotlin multiplatform oferă extensii pentru configurarea platformelor țintă, a source set-urilor și a binarelor framework, care sunt disponibile doar prin Kotlin DSL. Groovy nu suportă corect configurarea multi-platformă, de aceea proiectele KMM folosesc exclusiv KTS.

Configurarea KMM în KTS include blocuri non-standard: kotlin.target pentru specificarea platformelor, kotlin.sourceSets pentru organizarea codului comun și specific platformei, kotlin.cocoapods pentru integrarea cu CocoaPods și kotlin.jvmToolchain pentru selectarea JDK. Fiecare bloc are un API strict tipizat cu autocompletare în Android Studio, ceea ce este deosebit de valoros pentru configurarea complexă a proiectelor KMM cu mai multe platforme.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

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

Datorită tipizării statice KTS, dezvoltatorii KMM beneficiază de autocompletare pentru source set-uri și dependențe, verificarea tipurilor configurației framework și posibilitatea de refactorizare a numelor de platformă. KTS simplifică și depanarea: erorile în configurarea KMM sunt afișate ca erori de compilare Kotlin cu mesaje ușor de înțeles, spre deosebire de Groovy, unde erorile puteau fi ascunse până la executarea task-ului Gradle.