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. Пример ниже демонстрирует настройку приложения с двумя 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-модуля включает настройку target-платформ и 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 или version management. Благодаря статической типизации такие функции можно вызывать с проверкой параметров на этапе компиляции, что исключает ошибки в 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")
            }
        }
    }
}

// Usage in 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, затем корневой 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 предоставляет расширения для конфигурации target-платформ, 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-задачи.