Gradle KTS — o que é, Kotlin DSL para Gradle e sintaxe

O que é Gradle KTS?

Gradle KTS é um Kotlin DSL (Domain Specific Language) que oferece uma alternativa ao Groovy para escrever arquivos de configuração do Gradle. Em vez da sintaxe Groovy, os desenvolvedores usam Kotlin — uma linguagem estritamente tipada que verifica a correção da configuração em tempo de compilação. O KTS foi introduzido pela primeira vez no Gradle 5.0 em 2018 como um recurso experimental e alcançou estabilidade no Gradle 6.0.

O principal objetivo do KTS é eliminar as deficiências do Groovy em scripts de build. Groovy é uma linguagem de tipagem dinâmica onde erros de configuração aparecem apenas em tempo de execução ao executar uma tarefa. O KTS permite detectar os mesmos erros na etapa de edição de código graças à tipagem estática do Kotlin. Além disso, o KTS fornece acesso à API do Gradle com documentação completa de tipos, simplificando significativamente o aprendizado e uso de blocos de configuração complexos.

O ecossistema KTS é suportado por todas as principais ferramentas: Android Studio, IntelliJ IDEA, VS Code com o plugin Kotlin e Gradle Build Tool. Todos os plugins modernos (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) fornecem uma API amigável ao Kotlin com tipos explícitos, tornando o KTS a escolha preferida para novos projetos.

Como o Gradle KTS funciona

Gradle KTS usa o compilador Kotlin para processar arquivos .gradle.kts. O Gradle reconhece a extensão e passa os scripts para o mecanismo de script Kotlin, que os compila em classes. Essas classes são então executadas pelo Gradle para construir o modelo do projeto. A principal diferença do Groovy: os scripts KTS são compilados antecipadamente, não interpretados dinamicamente, permitindo detectar erros antes do início da execução das tarefas.

A arquitetura KTS é baseada em kotlin-scripting. Cada arquivo .gradle.kts é um script Kotlin com importações implícitas da API do Gradle. O desenvolvedor pode usar qualquer construto Kotlin: funções de extensão, lambdas, classes de dados e até declarar funções auxiliares dentro do script de build. O Gradle fornece um conjunto de funções de extensão para configuração tipada de blocos: dependencies, android, kotlin e outros.

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

Conversão de tipos no KTS

Uma das principais diferenças entre KTS e Groovy é o tratamento de tipos. No Groovy, todas as configurações aceitam Object, enquanto no KTS aceitam tipos específicos do Kotlin. Por exemplo, compileSdk aceita Int, não uma string. Isso elimina erros relacionados a tipos incorretos: no Groovy, compileSdk 34 e compileSdk "34" funcionam da mesma forma, enquanto no KTS apenas a primeira variante é válida. Esse rigor torna a configuração mais previsível e documentada.

Gradle KTS vs Groovy: comparação

Groovy foi o DSL original para Gradle e continua totalmente suportado. No entanto, o KTS oferece várias vantagens que o tornam a escolha recomendada para novos projetos. Tipagem estática, melhor desempenho de edição na IDE e sintaxe mais rigorosa são os principais motivos para migrar para o KTS. Ao mesmo tempo, o Groovy mantém sua vantagem em concisão para configurações simples.

O desempenho de compilação no KTS e Groovy é quase idêntico após a compilação dos scripts. Os scripts KTS demoram mais para compilar na primeira execução ou após limpar o cache, mas as compilações subsequentes funcionam na mesma velocidade que os scripts Groovy. Gradle armazena em cache os scripts KTS compilados no diretório de build, portanto a recompilação só ocorre quando o script muda.

A escolha entre KTS e Groovy em 2026 é clara: para novos projetos — KTS. Google, JetBrains e Gradle recomendam KTS para todos os novos projetos. O Groovy continua relevante para manutenção de projetos legados onde a migração é impraticável devido ao volume de configurações ou plugins específicos incompatíveis com KTS.

Exemplos de código: scripts de build em KTS

Vejamos blocos de configuração típicos em KTS para Android, Kotlin Multiplatform e Compose Multiplatform. Um projeto Android com KTS requer especificação explícita de tipos na configuração de buildTypes e productFlavors. O exemplo abaixo demonstra a configuração de um aplicativo com dois sabores.

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

Para Kotlin Multiplatform, o KTS é obrigatório — o Groovy não suporta corretamente a configuração de módulos multiplataforma. A configuração do módulo KMM inclui a configuração das plataformas alvo e source sets. O exemplo abaixo mostra a configuração do módulo compartilhado com iOS e 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")
        }
    }
}

Funções auxiliares e tarefas personalizadas

O KTS permite declarar funções auxiliares Kotlin dentro do script de build. Isso é especialmente útil para configurações repetitivas como signing configs ou gerenciamento de versões. Graças à tipagem estática, essas funções podem ser chamadas com validação de parâmetros em tempo de compilação, eliminando erros em configurações de assinatura antes da publicação no 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")
            }
        }
    }
}

// Uso em build.gradle.kts
configureSigning()

Migração de Groovy para KTS

A migração de Groovy para KTS é um processo que pode ser feito gradualmente. O Gradle suporta projetos mistos onde alguns módulos usam Groovy (build.gradle) e outros usam KTS (build.gradle.kts). O settings.gradle e o build.gradle raiz podem ser migrados primeiro, pois não dependem dos plugins dos módulos. O Google recomenda começar a migração com settings.gradle.kts, depois o build.gradle.kts raiz, e só então os módulos.

As principais etapas da migração incluem: substituir a sintaxe de closures por lambdas, adicionar sinais = para atribuição, substituir chaves de string por constantes tipadas e tipagem explícita de variáveis. Android Studio fornece conversão automática de Groovy para KTS para blocos simples, mas configurações complexas com closures aninhadas exigem reescrita manual.

Os problemas típicos de migração incluem chamadas implícitas de métodos Groovy que não têm equivalente em Kotlin e plugins que não fornecem uma API amigável ao Kotlin. Para o primeiro problema, o Gradle fornece compatibilidade através do withGroovyBuilder — um mecanismo que permite chamar métodos Groovy a partir do KTS. Para o segundo — é necessário aguardar uma atualização do plugin ou usá-lo em um módulo Groovy até a migração completa.

Gradle KTS para Kotlin Multiplatform

Kotlin Multiplatform é o projeto principal onde o KTS é um requisito obrigatório. O plugin kotlin multiplatform fornece extensões para configurar plataformas alvo, source sets e binários de framework que estão disponíveis apenas através do Kotlin DSL. O Groovy não suporta corretamente a configuração multiplataforma, portanto os projetos KMM usam exclusivamente KTS.

A configuração KMM no KTS inclui blocos não padrão: kotlin.target para especificar plataformas, kotlin.sourceSets para organizar código comum e específico de plataforma, kotlin.cocoapods para integração com CocoaPods e kotlin.jvmToolchain para seleção de JDK. Cada bloco tem uma API estritamente tipada com autocompletar no Android Studio, o que é especialmente valioso para configuração complexa de projetos KMM com múltiplas plataformas.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

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

Graças à tipagem estática do KTS, os desenvolvedores KMM obtêm autocompletar para source sets e dependências, verificação de tipos da configuração do framework e capacidade de refatorar nomes de plataformas. KTS também simplifica a depuração: erros na configuração KMM aparecem como erros de compilação Kotlin com mensagens claras, ao contrário do Groovy onde os erros podiam ficar ocultos até a execução de uma tarefa Gradle.