Gradle KTS — mi ez, Kotlin DSL a Gradle-hez és szintaxis

Mi az a Gradle KTS?

Gradle KTS — ez egy Kotlin DSL (Domain Specific Language), amely alternatívát nyújt a Groovy helyett a Gradle konfigurációs fájlok írásához. A Groovy szintaxis helyett a fejlesztők Kotlin-t használnak — egy szigorúan típusos nyelvet, amely a konfiguráció helyességét fordítási időben ellenőrzi. A KTS-t először a Gradle 5.0-ban vezették be 2018-ban kísérleti funkcióként, és a Gradle 6.0-ban érte el a stabilitást.

A KTS fő célja a Groovy hiányosságainak kiküszöbölése a build szkriptekben. Groovy — egy dinamikusan típusos nyelv, amelyben a konfigurációs hibák csak futási időben jelennek meg a feladatok végrehajtása során. A KTS lehetővé teszi ugyanazon hibák észlelését a kód szerkesztésének szakaszában a Kotlin statikus típusosságának köszönhetően. Emellett a KTS hozzáférést biztosít a Gradle API-hoz a típusok teljes dokumentációjával, ami jelentősen megkönnyíti az összetett konfigurációs blokkok tanulását és használatát.

A KTS ökoszisztémáját az összes fő eszköz támogatja: Android Studio, IntelliJ IDEA, VS Code Kotlin bővítménnyel és a Gradle Build Tool. Az összes modern bővítmény (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) Kotlin-barát API-t biztosít explicit típusokkal, ami a KTS-t az új projektek előnyben részesített választásává teszi.

Hogyan működik a Gradle KTS

Gradle KTS a Kotlin fordítót használja a .gradle.kts fájlok feldolgozásához. A Gradle felismeri a kiterjesztést, és a szkripteket a Kotlin szkriptmotorba küldi, amely osztályokba fordítja őket. Ezeket az osztályokat ezután a Gradle hajtja végre a projektmodell felépítéséhez. A legfontosabb különbség a Groovy-hoz képest: a KTS szkriptek előre lefordításra kerülnek, nem dinamikusan értelmeződnek, ami lehetővé teszi a hibák észlelését a feladatok végrehajtásának megkezdése előtt.

A KTS architektúrája a kotlin-scripting-re épül. Minden .gradle.kts fájl egy Kotlin szkript a Gradle API implicit importjaival. A fejlesztő bármilyen Kotlin szerkezetet használhat: kiterjesztési függvényeket, lambdákat, data osztályokat, és akár segédfüggvényeket is deklarálhat a build szkripten belül. A Gradle egy sor kiterjesztési függvényt biztosít a blokok típusos konfigurálásához: dependencies, android, kotlin és mások.

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

Típuskonverzió a KTS-ben

A KTS és a Groovy közötti egyik legfontosabb különbség a típusokkal való munka. A Groovy-ban minden konfiguráció Object-et fogad, a KTS-ben — konkrét Kotlin típusokat. Például a compileSdk Int-et fogad, nem stringet. Ez kiküszöböli a helytelen típushoz kapcsolódó hibákat: a Groovy-ban a compileSdk 34 és a compileSdk „34” ugyanúgy működik, a KTS-ben csak az első változat. Ez a szigeteltség a konfigurációt kiszámíthatóbbá és dokumentáltabbá teszi.

Gradle KTS vs Groovy: összehasonlítás

Groovy volt az eredeti DSL a Gradle-hez, és továbbra is teljes mértékben támogatott. A KTS azonban számos előnyt kínál, amelyek ajánlottá teszik új projektekhez. A statikus típusosság, jobb szerkesztési teljesítmény az IDE-ben és szigorúbb szintaxis — a KTS-re való áttérés fő okai. Ugyanakkor a Groovy megtartja a tömörség előnyét az egyszerű konfigurációkhoz.

A build teljesítménye a KTS és Groovy esetében gyakorlatilag azonos a szkriptek fordítása után. A KTS szkriptek az első indításkor vagy a gyorsítótár törlése után tovább fordulnak, de a későbbi buildek ugyanolyan sebességgel működnek, mint a Groovy szkriptek. A Gradle a lefordított KTS szkripteket a build könyvtárban gyorsítótárazza, így az újrafordítás csak a szkript megváltozásakor történik.

A KTS és Groovy közötti választás 2026-ban egyértelmű: új projektekhez — KTS. A Google, a JetBrains és a Gradle a KTS-t ajánlja minden új projekthez. A Groovy továbbra is releváns az örökölt projektek támogatásához, ahol a migráció nem célszerű a konfigurációk mennyisége vagy a KTS-sel nem kompatibilis specifikus bővítmények miatt.

Kódpéldák: build szkriptek KTS-ben

Tekintsük át a tipikus konfigurációs blokkokat KTS-ben Android, Kotlin Multiplatform és Compose Multiplatform esetében. Android projekt KTS-sel megköveteli a típusok explicit megadását a buildTypes és productFlavors konfigurációjában. Az alábbi példa egy két flavour-ral rendelkező alkalmazás konfigurációját mutatja be.

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

A Kotlin Multiplatform esetében a KTS kötelező — a Groovy nem támogatja megfelelően a többplatformos modulok konfigurációját. A KMM modul konfigurációja magában foglalja a célplatformok és source set-ek beállítását. Az alábbi példa egy shared modul konfigurációját mutatja iOS és Android rendszerekkel.

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

Segédfüggvények és egyéni feladatok

A KTS lehetővé teszi segéd Kotlin függvények deklarálását a build szkripten belül. Ez különösen kényelmes ismétlődő konfigurációkhoz, mint például signing configs vagy verziókezelés. A statikus típusosságnak köszönhetően az ilyen függvények paraméterellenőrzéssel hívhatók meg fordítási időben, ami kiküszöböli a signing konfigurációk hibáit a Google Play-ben történő közzététel előtt.

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

// Használat a build.gradle.kts fájlban
configureSigning()

Migráció Groovy-ról KTS-re

Migráció Groovy-ról KTS-re — egy fokozatosan végrehajtható folyamat. A Gradle támogatja a vegyes projekteket, ahol a modulok egy része Groovy-t (build.gradle), más része KTS-t (build.gradle.kts) használ. A settings.gradle és a root build.gradle fordíthatók le először, mivel nem függnek a modul bővítményeitől. A Google azt ajánlja, hogy a migrációt a settings.gradle.kts-sel kezdjük, majd a root build.gradle.kts-sel, és csak azután a modulokkal.

A migráció fő lépései: a closure szintaxis lambdákkal való helyettesítése, a = jelek hozzáadása a hozzárendeléshez, a string kulcsok típusos konstansokkal való helyettesítése és a változók explicit típusossá tétele. Az Android Studio automatikus Groovy → KTS konverziót biztosít az egyszerű blokkokhoz, de az összetett, egymásba ágyazott closures-okat tartalmazó konfigurációk kézi átírást igényelnek.

A migráció tipikus problémái közé tartoznak a Groovy metódusok implicit hívásai, amelyeknek nincs Kotlin megfelelőjük, valamint a bővítmények, amelyek nem biztosítanak Kotlin-barát API-t. Az első probléma megoldásához a Gradle kompatibilitást biztosít a withGroovyBuilder segítségével — egy olyan mechanizmussal, amely lehetővé teszi Groovy metódusok hívását KTS-ből. A másodikhoz — várni kell a bővítmény frissítésére, vagy használni kell a Groovy modulban a teljes migrációig.

Gradle KTS Kotlin Multiplatformhoz

Kotlin Multiplatform — a fő projekt, amelyben a KTS kötelező követelmény. A kotlin multiplatform bővítmény kiterjesztéseket biztosít a célplatformok, source set-ek és framework binárisok konfigurálásához, amelyek csak a Kotlin DSL-en keresztül érhetők el. A Groovy nem támogatja megfelelően a többplatformos konfigurációt, ezért a KMM projektek kizárólag KTS-t használnak.

A KMM konfigurációja KTS-ben nem szabványos blokkokat tartalmaz: kotlin.target a platformok megadásához, kotlin.sourceSets a közös és platformspecifikus kód szervezéséhez, kotlin.cocoapods a CocoaPods integrációhoz és kotlin.jvmToolchain a JDK kiválasztásához. Minden blokk szigorúan típusos API-val rendelkezik automatikus kiegészítéssel az Android Studio-ban, ami különösen értékes a több platformmal rendelkező összetett KMM projekt konfigurálásához.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

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

A KTS statikus típusosságának köszönhetően a KMM fejlesztők automatikus kiegészítést kapnak a source set-ekhez és függőségekhez, a framework konfiguráció típusellenőrzését, valamint a platformnevek refaktorálásának lehetőségét. A KTS emellett egyszerűsíti a hibakeresést: a KMM konfigurációs hibák Kotlin fordítási hibákként jelennek meg érthető üzenetekkel, ellentétben a Groovy-val, ahol a hibák elrejtőzhettek a Gradle feladat végrehajtásáig.