Gradle KTS — какво е това, Kotlin DSL за Gradle и синтаксис

Какво е Gradle KTS?

Gradle KTS — това е Kotlin DSL (Domain Specific Language), който предоставя алтернатива на Groovy за писане на конфигурационни файлове на Gradle. Вместо синтаксис на Groovy, разработчиците използват Kotlin — строго типизиран език, който проверява коректността на конфигурацията на етапа на компилация. KTS беше въведен за първи път в Gradle 5.0 през 2018 г. като експериментална функция и достигна стабилност в Gradle 6.0.

Основната цел на KTS е да елиминира недостатъците на Groovy в build скриптовете. Groovy — динамично типизиран език, при който грешките в конфигурацията се проявяват само по време на изпълнение при изпълнение на задачи. KTS позволява откриване на същите грешки на етапа на редактиране на кода благодарение на статичното типизиране на Kotlin. Допълнително, KTS предоставя достъп до API на Gradle с пълна документация на типовете, което значително улеснява изучаването и използването на сложни конфигурационни блокове.

Екосистемата на KTS се поддържа от всички основни инструменти: Android Studio, IntelliJ IDEA, VS Code с плъгин за Kotlin и Gradle Build Tool. Всички модерни плъгини (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) предоставят Kotlin-приятелски API с изрични типове, което прави KTS предпочитан избор за нови проекти.

Как работи Gradle KTS

Gradle KTS използва компилатора на Kotlin за обработка на .gradle.kts файлове. Gradle разпознава разширението и предава скриптовете на скриптовия двигател на Kotlin, който ги компилира в класове. Тези класове след това се изпълняват от Gradle за изграждане на модела на проекта. Ключовата разлика от Groovy: KTS скриптовете се компилират предварително, а не се интерпретират динамично, което позволява откриване на грешки преди започване на изпълнението на задачите.

Архитектурата на KTS се основава на kotlin-scripting. Всеки .gradle.kts файл е Kotlin скрипт с имплицитни импорти на API на Gradle. Разработчикът може да използва всякакви Kotlin конструкции: extension функции, ламбди, data класове и дори да декларира помощни функции вътре в build скрипта. Gradle предоставя набор от extension функции за типизирана конфигурация на блокове: dependencies, android, kotlin и други.

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

Преобразуване на типове в KTS

Една от ключовите разлики между KTS и Groovy е работата с типове. В Groovy всички конфигурации приемат Object, в KTS — конкретни Kotlin типове. Например compileSdk приема Int, а не низ. Това изключва грешки, свързани с неправилен тип: в Groovy compileSdk 34 и compileSdk „34“ работят еднакво, в KTS само първият вариант. Такава строгост прави конфигурацията по-предвидима и документирана.

Gradle KTS срещу Groovy: сравнение

Groovy беше оригиналният DSL за Gradle и остава напълно поддържан. Въпреки това, KTS предлага редица предимства, които го правят препоръчителен за нови проекти. Статично типизиране, по-добра производителност на редактиране в IDE и по-строг синтаксис — основните причини за преминаване към KTS. В същото време Groovy запазва предимството на краткост за прости конфигурации.

Производителността на изграждане на KTS и Groovy е практически идентична след компилация на скриптовете. KTS скриптовете се компилират по-дълго при първото стартиране или след изчистване на кеша, но следващите изграждания работят със същата скорост като Groovy скриптовете. Gradle кешира компилираните KTS скриптове в build директорията, така че прекомпилиране се случва само при промяна на скрипта.

Изборът между KTS и Groovy през 2026 г. е очевиден: за нови проекти — KTS. Google, JetBrains и Gradle препоръчват KTS за всички нови проекти. Groovy остава актуален за поддръжка на наследени проекти, където миграцията не е целесъобразна поради обема на конфигурациите или специфични плъгини, несъвместими с KTS.

Примери за код: build скриптове в KTS

Нека разгледаме типичните конфигурационни блокове в KTS за Android, Kotlin Multiplatform и Compose Multiplatform. Android проект с KTS изисква изрично посочване на типове в конфигурацията на buildTypes и productFlavors. Примерът по-долу демонстрира конфигурация на приложение с два flavour-а.

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

За Kotlin Multiplatform KTS е задължителен — Groovy не поддържа правилно конфигурация на мултиплатформени модули. Конфигурацията на KMM модул включва настройка на целеви платформи и source set-ове. Примерът по-долу показва конфигурация на shared модул с iOS и 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")
        }
    }
}

Помощни функции и персонализирани задачи

KTS позволява деклариране на помощни Kotlin функции вътре в build скрипта. Това е особено удобно за повтарящи се конфигурации като signing configs или управление на версии. Благодарение на статичното типизиране, такива функции могат да се извикват с проверка на параметрите на етапа на компилация, което изключва грешки в signing конфигурациите преди публикуване в 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")
            }
        }
    }
}

// Използване в build.gradle.kts
configureSigning()

Миграция от Groovy към KTS

Миграция от Groovy към KTS — процес, който може да се извършва постепенно. Gradle поддържа смесени проекти, където част от модулите използват Groovy (build.gradle), а част — KTS (build.gradle.kts). settings.gradle и root build.gradle могат да бъдат преобразувани първи, тъй като не зависят от плъгините на модулите. Google препоръчва да започнете миграцията с settings.gradle.kts, след това root build.gradle.kts и едва след това модулите.

Основните стъпки на миграцията включват: замяна на синтаксиса на closures с ламбди, добавяне на знаци = за присвояване, замяна на низови ключове с типизирани константи и изрично типизиране на променливи. Android Studio предоставя автоматично конвертиране от Groovy към KTS за прости блокове, но сложни конфигурации с вложени closures изискват ръчно пренаписване.

Типичните проблеми при миграция включват имплицитни извиквания на методи на Groovy, които нямат Kotlin еквивалент, и плъгини, които не предоставят Kotlin-приятелски API. За решаване на първия проблем Gradle предоставя съвместимост чрез withGroovyBuilder — механизъм, който позволява извикване на Groovy методи от KTS. За втория — трябва да изчакате актуализация на плъгина или да го използвате в Groovy модула до пълна миграция.

Gradle KTS за Kotlin Multiplatform

Kotlin Multiplatform — основният проект, в който KTS е задължително изискване. Плъгинът kotlin multiplatform предоставя разширения за конфигурация на целеви платформи, source set-ове и framework двоични файлове, които са достъпни само чрез Kotlin DSL. Groovy не поддържа правилно мултиплатформена конфигурация, затова KMM проектите използват изключително KTS.

Конфигурацията на KMM в KTS включва нестандартни блокове: kotlin.target за посочване на платформи, kotlin.sourceSets за организиране на общ и платформено-специфичен код, kotlin.cocoapods за интеграция с CocoaPods и kotlin.jvmToolchain за избор на JDK. Всеки блок има строго типизиран API с автоматично довършване в Android Studio, което е особено ценно за сложна конфигурация на KMM проект с множество платформи.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

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

Благодарение на статичното типизиране на KTS, KMM разработчиците получават автоматично довършване за source set-ове и зависимости, проверка на типовете на framework конфигурацията и възможност за рефакториране на платформени имена. KTS също така опростява отстраняването на грешки: грешките в KMM конфигурацията се показват като грешки при компилация на Kotlin с разбираеми съобщения, за разлика от Groovy, където грешките можеха да бъдат скрити до изпълнение на Gradle задача.