Gradle KTS — cos'è, Kotlin DSL per Gradle e sintassi

Cos'è Gradle KTS?

Gradle KTS è un Kotlin DSL (Domain Specific Language) che offre un'alternativa a Groovy per scrivere file di configurazione Gradle. Invece della sintassi Groovy, gli sviluppatori usano Kotlin — un linguaggio rigorosamente tipizzato che verifica la correttezza della configurazione in fase di compilazione. KTS è stato introdotto per la prima volta in Gradle 5.0 nel 2018 come funzionalità sperimentale e ha raggiunto la stabilità in Gradle 6.0.

L'obiettivo principale di KTS è eliminare le carenze di Groovy negli script di build. Groovy è un linguaggio a tipizzazione dinamica in cui gli errori di configurazione compaiono solo a runtime durante l'esecuzione di un'attività. KTS consente di rilevare gli stessi errori in fase di modifica del codice grazie alla tipizzazione statica di Kotlin. Inoltre, KTS fornisce accesso all'API di Gradle con documentazione completa dei tipi, semplificando notevolmente l'apprendimento e l'uso di blocchi di configurazione complessi.

L'ecosistema KTS è supportato da tutti i principali strumenti: Android Studio, IntelliJ IDEA, VS Code con il plugin Kotlin e Gradle Build Tool. Tutti i plugin moderni (Android Gradle Plugin, Kotlin Multiplatform, Protobuf, Compose) forniscono un'API compatibile con Kotlin con tipi espliciti, rendendo KTS la scelta preferita per i nuovi progetti.

Come funziona Gradle KTS

Gradle KTS utilizza il compilatore Kotlin per elaborare i file .gradle.kts. Gradle riconosce l'estensione e passa gli script al motore di scripting Kotlin, che li compila in classi. Queste classi vengono poi eseguite da Gradle per costruire il modello di progetto. La differenza principale da Groovy: gli script KTS vengono compilati in anticipo, non interpretati dinamicamente, consentendo di rilevare gli errori prima dell'inizio dell'esecuzione delle attività.

L'architettura KTS si basa su kotlin-scripting. Ogni file .gradle.kts è uno script Kotlin con import impliciti dell'API Gradle. Lo sviluppatore può utilizzare qualsiasi costrutto Kotlin: funzioni di estensione, lambda, classi di dati e persino dichiarare funzioni ausiliarie all'interno dello script di build. Gradle fornisce un insieme di funzioni di estensione per la configurazione tipizzata di blocchi: dependencies, android, kotlin e altri.

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

Conversione dei tipi in KTS

Una delle differenze principali tra KTS e Groovy è la gestione dei tipi. In Groovy, tutte le configurazioni accettano Object, mentre in KTS accettano tipi Kotlin specifici. Ad esempio, compileSdk accetta Int, non una stringa. Ciò elimina gli errori relativi a tipi errati: in Groovy, compileSdk 34 e compileSdk "34" funzionano allo stesso modo, mentre in KTS solo la prima variante è valida. Questo rigore rende la configurazione più prevedibile e documentata.

Gradle KTS vs Groovy: confronto

Groovy era il DSL originale per Gradle e rimane completamente supportato. Tuttavia, KTS offre diversi vantaggi che lo rendono la scelta raccomandata per i nuovi progetti. Tipizzazione statica, migliori prestazioni di modifica nell'IDE e sintassi più rigorosa sono i motivi principali per passare a KTS. Allo stesso tempo, Groovy mantiene il suo vantaggio in termini di concisione per configurazioni semplici.

Le prestazioni di build su KTS e Groovy sono quasi identiche dopo la compilazione degli script. Gli script KTS richiedono più tempo per la compilazione al primo avvio o dopo aver cancellato la cache, ma le build successive funzionano alla stessa velocità degli script Groovy. Gradle memorizza nella cache gli script KTS compilati nella directory di build, quindi la ricompilazione avviene solo quando lo script cambia.

La scelta tra KTS e Groovy nel 2026 è chiara: per i nuovi progetti — KTS. Google, JetBrains e Gradle raccomandano KTS per tutti i nuovi progetti. Groovy rimane rilevante per la manutenzione di progetti legacy dove la migrazione è poco pratica a causa del volume di configurazioni o di plugin specifici incompatibili con KTS.

Esempi di codice: script di build in KTS

Esaminiamo i blocchi di configurazione tipici in KTS per Android, Kotlin Multiplatform e Compose Multiplatform. Un progetto Android con KTS richiede la specifica esplicita dei tipi nella configurazione di buildTypes e productFlavors. L'esempio seguente mostra la configurazione di un'applicazione con due 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"
        }
    }
}

Per Kotlin Multiplatform, KTS è obbligatorio — Groovy non supporta correttamente la configurazione di moduli multipiattaforma. La configurazione del modulo KMM include l'impostazione delle piattaforme di destinazione e dei source set. L'esempio seguente mostra la configurazione del modulo condiviso con 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")
        }
    }
}

Funzioni ausiliarie e attività personalizzate

KTS consente di dichiarare funzioni Kotlin ausiliarie all'interno dello script di build. Ciò è particolarmente utile per configurazioni ripetitive come le configurazioni di firma o la gestione delle versioni. Grazie alla tipizzazione statica, queste funzioni possono essere chiamate con validazione dei parametri in fase di compilazione, eliminando errori nelle configurazioni di firma prima della pubblicazione su 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")
            }
        }
    }
}

// Utilizzo in build.gradle.kts
configureSigning()

Migrazione da Groovy a KTS

La migrazione da Groovy a KTS è un processo che può essere eseguito gradualmente. Gradle supporta progetti misti in cui alcuni moduli utilizzano Groovy (build.gradle) e altri KTS (build.gradle.kts). Il settings.gradle e il build.gradle root possono essere migrati per primi poiché non dipendono dai plugin dei moduli. Google raccomanda di iniziare la migrazione con settings.gradle.kts, poi il build.gradle.kts root, e solo successivamente i moduli.

I passaggi principali della migrazione includono: sostituzione della sintassi closure con lambda, aggiunta del segno = per l'assegnazione, sostituzione delle chiavi stringa con costanti tipizzate e tipizzazione esplicita delle variabili. Android Studio fornisce conversione automatica da Groovy a KTS per blocchi semplici, ma configurazioni complesse con closure annidate richiedono riscrittura manuale.

I problemi tipici di migrazione includono chiamate implicite a metodi Groovy che non hanno un equivalente Kotlin e plugin che non forniscono un'API compatibile con Kotlin. Per il primo problema, Gradle fornisce compatibilità tramite withGroovyBuilder — un meccanismo che consente di chiamare metodi Groovy da KTS. Per il secondo — è necessario attendere un aggiornamento del plugin o utilizzarlo in un modulo Groovy fino alla migrazione completa.

Gradle KTS per Kotlin Multiplatform

Kotlin Multiplatform è il progetto principale in cui KTS è un requisito obbligatorio. Il plugin kotlin multiplatform fornisce estensioni per configurare piattaforme di destinazione, source set e binari di framework che sono disponibili solo tramite Kotlin DSL. Groovy non supporta correttamente la configurazione multipiattaforma, quindi i progetti KMM utilizzano esclusivamente KTS.

La configurazione KMM in KTS include blocchi non standard: kotlin.target per specificare le piattaforme, kotlin.sourceSets per organizzare il codice comune e specifico della piattaforma, kotlin.cocoapods per l'integrazione con CocoaPods e kotlin.jvmToolchain per la selezione del JDK. Ogni blocco ha un'API rigorosamente tipizzata con autocompletamento in Android Studio, che è particolarmente preziosa per la configurazione complessa di progetti KMM con più piattaforme.

kotlin {
    iosArm64()
    iosSimulatorArm64()
    iosX64()

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

Grazie alla tipizzazione statica di KTS, gli sviluppatori KMM ottengono autocompletamento per source set e dipendenze, controllo dei tipi della configurazione del framework e la possibilità di refactoring dei nomi delle piattaforme. KTS semplifica anche il debugging: gli errori nella configurazione KMM appaiono come errori di compilazione Kotlin con messaggi chiari, a differenza di Groovy dove gli errori potevano rimanere nascosti fino all'esecuzione di un'attività Gradle.