settings.gradle: cos'è, inclusione di moduli e pluginManagement

Cos'è settings.gradle?

settings.gradle (o settings.gradle.kts per Kotlin DSL) è un file che Gradle esegue durante la fase di Initialization. Definisce la gerarchia del progetto, include i modelli e configura i repository per plugin e dipendenze. Senza settings.gradle, Gradle non sa quali moduli compilare né quali plugin sono disponibili. In un progetto a modulo singolo, settings.gradle può essere assente — Gradle usa valori predefiniti, ma è obbligatorio per progetti multimodulo.

Il file settings.gradle si trova nella radice del progetto, accanto al build.gradle radice. Una struttura tipica della radice del progetto: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle viene eseguito prima di build.gradle — durante la fase di Initialization, Gradle costruisce l'albero del progetto (Project nell'API di Gradle). Dopo l'Initialization, inizia la Configuration — l'esecuzione del build.gradle di ogni modulo.

Storicamente, settings.gradle è apparso in Gradle 0.7 (2010) e inizialmente conteneva solo direttive include. Con l'evoluzione di Gradle, sono stati aggiunti pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) e versionCatalogs (Gradle 7.4). Il settings.gradle moderno è un potente file di configurazione che centralizza la gestione di plugin, repository e versioni per l'intero progetto. Google impone queste capacità nell'Android Gradle Plugin a partire da AGP 8.0.

settings.gradle vs build.gradle

settings.gradle gestisce la struttura del progetto e le impostazioni globali (plugin, repository). build.gradle gestisce la compilazione (dipendenze, configurazioni Android, attività). settings.gradle viene eseguito per primo e ha accesso all'API Settings. build.gradle viene eseguito dopo e ha accesso all'API Project. Nessuna configurazione a livello di modulo (blocco android, dependencies) può stare in settings.gradle — sarebbe un errore.

Inclusione di moduli tramite include

La direttiva include è il cuore di settings.gradle. Indica a Gradle quali moduli devono partecipare alla compilazione. L'argomento di include è una stringa con il percorso del modulo: include(":app") include un modulo nella radice, include(":core:network") include un modulo nella sottodirectory core/network/. I due punti all'inizio indicano che il percorso è relativo alla radice del progetto. Dopo include, Gradle trova automaticamente build.gradle nella directory specificata e aggiunge il modulo all'albero del progetto.

Ogni include crea un Project nell'API di Gradle con il nome uguale alla stringa include. Il nome del progetto viene utilizzato in implementation(project(":module")) nei build.gradle degli altri moduli. Se un modulo non è incluso tramite include, farvi riferimento da un altro modulo causerà un errore “Project not found”. Android Studio IDE utilizza anche settings.gradle per visualizzare i moduli nel pannello Project — i moduli senza include non sono visibili nell'albero dei file.

include supporta included builds e composite builds tramite includeBuild("../library-project"). Ciò consente di includere interi progetti Gradle come moduli esterni. Gli included builds sono utili per sviluppare librerie in parallelo con l'applicazione: le modifiche alla libreria sono immediatamente visibili nell'applicazione senza pubblicazione in un repository Maven. In una compilazione di produzione, includeBuild viene sostituito con una dipendenza Maven normale.

// settings.gradle.kts — struttura tipica
rootProject.name = "MyApp"

// Moduli dell'applicazione
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Inclusione di una libreria esterna (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Blocco di gestione dei plugin

Strategia di risoluzione

pluginManagement è un blocco in settings.gradle che determina da dove caricare i plugin Gradle. È apparso in Gradle 6.8 per la gestione centralizzata dei plugin prima della loro applicazione. All'interno di pluginManagement si trovano: repositories (elenco dei repository per trovare plugin), resolutionStrategy (regole di risoluzione delle versioni) e plugins (dichiarazione esplicita delle versioni dei plugin). Se pluginManagement non è definito, Gradle usa i repository da build.gradle — ma i plugin vengono cercati solo dopo essere stati dichiarati, causando errori se un plugin non viene trovato.

Nei progetti Android, pluginManagement è obbligatorio se si utilizzano Version Catalogs o Convention Plugins. Senza pluginManagement, Gradle non riesce a trovare il plugin com.android.application quando applicato in build.gradle.kts. Una configurazione tipica: repositories contiene google() (plugin Android), mavenCentral() (plugin di terze parti) e gradlePluginPortal() (plugin ufficiali Gradle).

pluginManagement supporta anche plugins — dichiarare plugin con versioni che vengono poi applicati in build.gradle senza specificare la versione. Ciò centralizza le versioni dei plugin: se 10 moduli applicano kotlin-android, la versione viene specificata una volta in pluginManagement. Importante: pluginManagement.plugins è solo una dichiarazione. Il plugin stesso viene applicato in build.gradle tramite plugins { id("org.jetbrains.kotlin.android") }.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = "https://jitpack.io" }
    }

    // Versioni dei plugin — centralizzate
    plugins {
        id("com.android.application") version "8.7.0"
        id("com.android.library") version "8.7.0"
        id("org.jetbrains.kotlin.android") version "2.0.21"
        id("com.google.devtools.ksp") version "2.0.21-1.0.25"
    }

    resolutionStrategy {
        // Versione forzata del plugin per tutti i moduli
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Applicazione dei plugin — apply false (non applicare alla radice)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Gestione della risoluzione delle dipendenze

Modalità di repositoriesMode

dependencyResolutionManagement è un blocco in settings.gradle che gestisce centralmente i repository per tutti i moduli. È apparso in Gradle 7.0 come alternativa alla dichiarazione di repositories in ogni build.gradle. All'interno del blocco vengono impostati repositoriesMode (modalità: PREFER_PROJECT, PREFER_SETTINGS o FAIL_ON_PROJECT_REPOS) e repositories (elenco dei repository). Se repositoriesMode = PREFER_SETTINGS, i repository a livello di modulo vengono ignorati — viene utilizzato solo l'elenco centralizzato.

repositoriesMode può assumere tre valori. PREFER_SETTINGS — i repository da build.gradle vengono ignorati, vengono utilizzati solo quelli da settings.gradle. PREFER_PROJECT — i repository di build.gradle hanno priorità su settings.gradle. FAIL_ON_PROJECT_REPOS — se un modulo dichiara propri repository, Gradle genera un errore. Per i nuovi progetti, si consiglia PREFER_SETTINGS — garantisce che tutti i moduli utilizzino gli stessi repository ed elimina la duplicazione.

repositoriesMode = FAIL_ON_PROJECT_REPOS è particolarmente utile nei team: se uno sviluppatore aggiunge un repository a un solo modulo e gli altri non lo vedono, si verifica il problema “works on my machine”. FAIL_ON_PROJECT_REPOS forza tutti i repository a essere dichiarati centralmente in settings.gradle, prevenendo tali situazioni. Google raccomanda FAIL_ON_PROJECT_REPOS per tutti i progetti Android a partire da AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — tutti i repository solo qui
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

    repositories {
        google()
        mavenCentral()
        maven { url = "https://jitpack.io" }

        // Repository Maven privato
        maven {
            url = "https://maven.pkg.github.com/company/internal-lib"
            credentials {
                username = providers.gradleProperty("gpr.user")
                    .getOrNull() ?: System.getenv("GPR_USER") ?: ""
                password = providers.gradleProperty("gpr.key")
                    .getOrNull() ?: System.getenv("GPR_KEY") ?: ""
            }
        }
    }
}

// In build.gradle del modulo, repositories non sono più necessari!
// Tutti i repository centralizzati in settings.gradle

Cataloghi di versioni in settings.gradle

Version Catalogs è un modo centralizzato per gestire le versioni delle dipendenze tramite un file TOML. A partire da Gradle 7.4, i cataloghi di versioni sono il meccanismo raccomandato per tutti i progetti Android. Il file gradle/libs.versions.toml contiene tre sezioni: [versions] (versioni), [libraries] (dipendenze), [plugins] (plugin). In settings.gradle, il catalogo di versioni viene collegato tramite @Suppress("UnstableApiUsage") e enableFeaturePreview("VERSION_CATALOGS") (nelle versioni precedenti di Gradle).

Dopo aver collegato il catalogo di versioni, le dipendenze dei moduli in build.gradle vengono specificate tramite libs: implementation(libs.retrofit). L'IDE fornisce il completamento automatico per libs. Il catalogo genera automaticamente accessor type-safe: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. I Bundles sono gruppi di dipendenze che possono essere inclusi con una singola riga. I cataloghi di versioni supportano anche l'ereditarietà — è possibile collegare più file TOML.

Vantaggi dei cataloghi di versioni: unico posto per le versioni (non è necessario cercare in tutti i build.gradle); accesso type-safe (un errore nel nome libs viene rilevato in compilazione, non in esecuzione); aggiornamenti automatici (Dependabot e Renovate supportano TOML); compatibilità con Convention Plugins. Google Firebase e AndroidX distribuiscono propri cataloghi TOML. Per migrare ai cataloghi di versioni, esistono plugin che trasferiscono automaticamente le versioni da build.gradle a TOML.

# gradle/libs.versions.toml
[versions]
agp = "8.7.0"
kotlin = "2.0.21"
composeBom = "2024.12.01"
retrofit = "2.11.0"
coroutines = "1.9.0"

[libraries]
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }
kotlin-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }
compose-ui = { module = "androidx.compose.ui:ui" }

[bundles]
compose = ["compose-ui", "compose-material3"]

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

Impostazioni avanzate: includeBuild e funzionalità incubanti

includeBuild è una direttiva per creare un composite build: includere un progetto Gradle esterno come parte della compilazione corrente. A differenza di include (che include un modulo), includeBuild include un intero progetto con il proprio settings.gradle, moduli e plugin. I composite build vengono utilizzati per: sviluppare librerie (analisi, rete) in parallelo con l'applicazione; includere Convention Plugins da un repository separato; integrare moduli build-logic.

Funzionalità incubanti (Incubating Features) sono opzioni sperimentali di Gradle che vengono attivate tramite enableFeaturePreview("FEATURE_NAME"). In AGP 8.7+, sono disponibili: TYPESAFE_PROJECT_ACCESSORS (accesso type-safe ai progetti in un progetto multimodulo: invece di project(":core:network"), si può scrivere projects.core.network), STABLE_CONFIGURATION_CACHE (caching stabile della configurazione), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (trasformazione degli artefatti). Le funzionalità incubanti possono essere attivate in produzione, ma l'API potrebbe cambiare nelle versioni future.

Gradle Enterprise e Build Scan sono anche configurati tramite settings.gradle: plugins { id("com.gradle.enterprise") } con un blocco gradleEnterprise. Build Scan è un servizio cloud che mostra informazioni dettagliate su ogni compilazione: tempo di esecuzione di ogni attività, caching, errori. L'attivazione di Build Scan aiuta a diagnosticare problemi di velocità di compilazione. Build Scan è gratuito per progetti open source.

// Funzionalità incubanti
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
enableFeaturePreview("STABLE_CONFIGURATION_CACHE")

// Gradle Enterprise / Build Scan
plugins {
    id("com.gradle.enterprise") version "3.18"
}

gradleEnterprise {
    buildScan {
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        publishAlwaysIf(true)
    }
}

// Utilizzo di type-safe project accessors in build.gradle
// Invece di: implementation(project(":core:network"))
// Si può: implementation(projects.core.network)