build.gradle: cos'è, sintassi e configurazione in Android

Cos'è build.gradle?

build.gradle è uno script di build nel linguaggio Groovy (estensione .gradle) o Kotlin (.gradle.kts) che gestisce tutti gli aspetti della compilazione di un'applicazione Android. Gradle è un sistema di build automatico adottato da Google nel 2013 come standard per Android. build.gradle descrive: quali plugin sono applicati (Android, Kotlin, librerie), quali dipendenze sono collegate, quali versioni SDK sono utilizzate, come firmare l'applicazione e dove pubblicare.

Il processo di build include tre fasi: Initialization (scoperta dei moduli), Configuration (esecuzione degli script build.gradle), Execution (esecuzione dei task). build.gradle viene eseguito durante la fase Configuration, quando Gradle crea il grafo dei task. In questo momento vengono determinati i Build Variants, calcolate le dipendenze e configurati i task. Importante: build.gradle è codice, non solo configurazione. Possono essere utilizzate condizioni, cicli, chiamate a metodi e script esterni.

I file Gradle sono memorizzati nella radice del modulo (app/build.gradle) e nella radice del progetto (build.gradle). Inoltre, Gradle supporta apply from — inclusione di script Gradle esterni. Ciò consente di estrarre la logica ripetitiva in file con impostazioni condivise. Con l'avvento dei Convention Plugins (AGP 7+), apply from è considerato obsoleto — i Convention Plugins forniscono un modo type-safe e componibile per riutilizzare la configurazione tra i moduli.

Evoluzione di build.gradle

Dal 2013, la sintassi di build.gradle ha subito cambiamenti significativi: da Groovy con configurazioni dinamiche a Kotlin DSL con controlli in fase di compilazione. AGP si è evoluto dalla versione 1.0 alla 8.7 (2025). Pietre miliari chiave: AGP 3.0 (Java 8 desugar, nuova variant API), AGP 4.0 (view binding, Java 11), AGP 7.0 (Kotlin DSL predefinito, Java 11 minimo), AGP 8.0 (classi R non transitive, build config in Kotlin), AGP 8.7 (KSP invece di kapt, configurazione veloce).

Project-level e Module-level build.gradle

Project-level build.gradle (radice) definisce plugin, repository e configurazioni comuni a tutti i moduli. Blocchi principali: plugins (dichiarazioni di plugin Gradle), repositories (fonti di dipendenze: mavenCentral, google, jitpack). Il build.gradle radice di solito non ha un blocco android — appare nei moduli. Project-level può anche contenere un blocco subprojects per la configurazione comune di tutti i sottoprogetti, sebbene i Convention Plugins siano preferibili.

Module-level build.gradle (ad esempio, app/build.gradle) descrive un modulo specifico. Se il modulo è un'applicazione, applica il plugin com.android.application. Se è una libreria — com.android.library. Module-level contiene: blocco android (compileSdk, defaultConfig, buildTypes, productFlavors), blocco dependencies (dipendenze del modulo) e opzionalmente blocchi per la configurazione di test e impacchettamento. Module-level viene eseguito dopo project-level e può sovrascrivere le impostazioni comuni.

A partire da AGP 8.0, il build.gradle radice può utilizzare version catalogs (libs.versions.toml) per la gestione centralizzata delle versioni delle dipendenze. Un version catalog è un file nella directory gradle/ che contiene versioni, librerie e plugin. In build.gradle le dipendenze vengono collegate tramite libs: implementation(libs.retrofit). I version catalogs sono obbligatori per i nuovi progetti e raccomandati per tutti i progetti con tre o più moduli.

// settings.gradle.kts — radice del progetto
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (project-level)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (module-level)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy vs Kotlin DSL

Groovy è un linguaggio JVM dinamico che era la sintassi originale di Gradle. Gli script Groovy (.gradle) utilizzano la tipizzazione dinamica: si possono omettere i tipi, usare stringhe con o senza virgolette, chiamare metodi che non esistono in fase di compilazione. La flessibilità di Groovy è anche il suo difetto: l'IDE non può verificare la sintassi e i tipi fino all'esecuzione dello script, causando errori a runtime dovuti a nomi di parametri o tipi errati.

Kotlin DSL (.gradle.kts) utilizza la tipizzazione statica di Kotlin. L'IDE verifica i tipi, suggerisce i parametri disponibili tramite autocompletamento e evidenzia gli errori in fase di modifica. Kotlin DSL è più lento durante la fase Configuration (a causa della compilazione dei file .kts in bytecode), ma Google migliora continuamente le prestazioni: AGP 8.5+ utilizza Gradle Configuration Cache e Caching Kotlin DSL compilation, riducendo la differenza a 1-2 secondi.

Google raccomanda Kotlin DSL per tutti i nuovi progetti e la migrazione graduale di quelli esistenti. La migrazione da Groovy a Kotlin DSL è semplice: le virgolette vengono sostituite con parentesi, vengono aggiunti i tipi, gli operatori vengono convertiti in funzioni. La maggior parte delle librerie fornisce esempi di Kotlin DSL nella propria documentazione. Per i casi complessi (Custom Plugin, Task Graph), Kotlin DSL fornisce un'API type-safe e previene errori che in Groovy vengono scoperti solo a runtime. I version catalogs (libs.versions.toml) funzionano allo stesso modo con entrambe le sintassi.

Blocco android: configurazione dell'applicazione

compileSdk, minSdk e targetSdk

Blocco android è l'elemento centrale del module-level build.gradle. Al suo interno vengono configurati: namespace (per R e BuildConfig), compileSdk, defaultConfig, buildTypes, productFlavors, sourceSets, compileOptions, packaging, bundle. Tutti i parametri del blocco android si applicano solo ai moduli Android. Se il modulo è una libreria, viene utilizzato il plugin della libreria invece di application e applicationId è assente dal blocco android.

compileSdk è la versione SDK con cui viene compilato il codice. Dovrebbe essere l'ultima API Android (al momento della scrittura — 35). minSdk è la versione API minima supportata. targetSdk è la versione a cui mira l'applicazione (le modifiche comportamentali di questa versione vengono applicate). La differenza tra compileSdk e targetSdk: compileSdk determina le API disponibili, targetSdk determina il comportamento a runtime. Raccomandazione: compileSdk = latest, targetSdk = latest - 1 (per testare l'adattamento alle nuove modifiche).

compileOptions imposta la compatibilità Java: sourceCompatibility e targetCompatibility. AGP 8+ richiede Java 17+ per la compilazione. packaging gestisce l'inclusione di file dalle librerie: exclude, merge, pickFirst per risolvere i conflitti META-INF. buildFeatures abilita/disabilita ViewBinding, DataBinding, Compose. aaptOptions configura l'elaborazione delle risorse: ignoreAssetsPattern, cruncherEnabled. Ogni elemento del blocco android ottimizza un aspetto specifico della build.

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

Gestione delle dipendenze

BOM (Bill of Materials)

Dipendenze in build.gradle sono librerie e modelli collegati al progetto. Il blocco dependencies si trova allo stesso livello del blocco android. Gradle supporta diverse configurazioni: implementation (la libreria è disponibile in questo modulo, non transitiva), api (la libreria è disponibile transitivamente per i moduli dipendenti), compileOnly (solo per la compilazione, non inclusa nell'APK), runtimeOnly (solo a runtime), annotationProcessor / ksp (processori di annotazioni), testImplementation (solo per test), androidTestImplementation (solo per test strumentati).

A partire da AGP 8.0, classi R non transitive — ogni libreria ha la propria classe R, prevenendo conflitti di risorse. Nel blocco dependencies è importante utilizzare le configurazioni corrette: implementation non espone dipendenze transitive, accelerando la build. api le espone — utilizzato quando una libreria esporta tipi da un'altra libreria (ad esempio, Retrofit utilizza i tipi OkHttp nella sua API pubblica).

Per la gestione delle versioni si raccomanda l'uso di BOM (Bill of Materials) — un file di build che definisce versioni compatibili di librerie. Firebase BOM: implementation(platform("com.google.firebase:firebase-bom:33.0.0")). Dopo aver collegato BOM, è possibile specificare solo il nome della libreria senza versione — BOM selezionerà automaticamente una versione compatibile. Ciò elimina i conflitti tra dipendenze transitive di diverse librerie. I BOM sono disponibili per Firebase, Compose, Kotlin, Ktor, AndroidX.

dependencies {
    // BOM — gestione delle versioni
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidX e Compose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase (versioni da BOM)
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // Testing
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

build.gradle nei progetti multimodulo

Nei progetti multimodulo, ogni modulo ha il proprio build.gradle. Per collegare un modulo a un altro, si utilizza la sintassi implementation(project(":module-name")). Gradle ricostruisce automaticamente il modulo se la sua configurazione è cambiata. L'architettura multimodulo migliora il tempo di build (build incrementale, parallelismo) e separa le responsabilità tra moduli di funzionalità, moduli core e librerie.

Il problema principale dei progetti multimodulo è la duplicazione della configurazione. Se 10 moduli hanno lo stesso minSdk, compileSdk e dipendenze Compose, sono 10 copie in diversi build.gradle. La soluzione sono i Convention Plugins (precedentemente buildSrc). Un Convention Plugin è un plugin Gradle scritto in Kotlin che viene applicato ai moduli: plugins { id("myapp.android.library") }. Il plugin contiene la configurazione comune e le modifiche vengono applicate immediatamente a tutti i moduli.

Per organizzare i Convention Plugins si utilizza la directory build-logic/ nella radice del progetto. Contiene includeBuild in settings.gradle e plugin Kotlin. I Convention Plugins possono essere pubblicati in un repository maven per il riutilizzo tra progetti. Google raccomanda i Convention Plugins come standard per i progetti multimodulo, sostituendo subprojects { } e apply from. Il passaggio ai Convention Plugins riduce il build.gradle del modulo a 10-15 righe.

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — dopo Convention Plugin
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}