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 — динамічно типізована мова, в якій помилки конфігурації проявляються тільки в runtime під час виконання завдання. 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 vs 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. Приклад нижче демонструє налаштування застосунку з двома варіантами.

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 та кореневий build.gradle можуть бути переведені першими, оскільки вони не залежать від плагінів модулів. Google рекомендує починати міграцію з settings.gradle.kts, потім кореневий 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-завдання.