Esegui la migrazione della build ai cataloghi delle versioni

I cataloghi delle versioni di Gradle ti consentono di aggiungere e gestire dipendenze e plug-in in modo scalabile. L'utilizzo dei cataloghi delle versioni di Gradle semplifica la gestione delle dipendenze e dei plug-in quando hai più moduli. Anziché impostare come hardcoded i nomi e le versioni delle dipendenze nei singoli file di build e aggiornare ogni voce ogni volta che devi eseguire l'upgrade di una dipendenza, puoi creare un catalogo delle versioni centrale delle dipendenze a cui i vari moduli possono fare riferimento in modo sicuro per i tipi con l'assistenza di Android Studio.

Questa pagina fornisce informazioni di base sulla migrazione della tua app per Android ai cataloghi delle versioni. Per saperne di più, consulta Aggiungi dipendenze di build e la documentazione di Gradle.

Crea un file del catalogo delle versioni

Inizia creando un file del catalogo delle versioni. Nella cartella gradle del progetto principale, crea un file denominato libs.versions.toml. Gradle cerca il catalogo nel file libs.versions.toml per impostazione predefinita, pertanto ti consigliamo di utilizzare questo nome predefinito.

Nel file libs.versions.toml, aggiungi queste sezioni:

[versions]

[libraries]

[plugins]

Le sezioni vengono utilizzate come segue:

  • Nel blocco versions, definisci le variabili che contengono le versioni delle tue dipendenze e dei tuoi plug-in. Queste variabili vengono utilizzate nei blocchi successivi (i blocchi libraries e plugins).
  • Nel blocco libraries, definisci le dipendenze.
  • Nel blocco plugins, definisci i plug-in.

Passi per la migrazione

Ti consigliamo di eseguire i passaggi nell'ordine indicato. Una build può utilizzare dipendenze e plug-in da script di build e cataloghi contemporaneamente, quindi prenditi il tempo necessario per eseguire la migrazione delle dipendenze e dei plug-in singolarmente.

Il processo di migrazione è il seguente:

  1. Aggiungi la nuova voce al catalogo.
  2. Sincronizza il tuo progetto Android.
  3. Sostituisci la dichiarazione della stringa precedente con l'accessor type-safe del catalogo.

Esegui la migrazione delle dipendenze

Aggiungi una voce per ogni dipendenza nelle sezioni versions e libraries del file libs.versions.toml. Sincronizza il progetto, quindi sostituisci le relative dichiarazioni nei file di build con i nomi del catalogo.

Questo snippet di codice mostra il file build.gradle.kts prima di rimuovere la dipendenza:

Kotlin

dependencies {
    implementation("androidx.core:core-ktx:1.9.0")

}

Alla moda

dependencies {
    implementation 'androidx.core:core-ktx:1.9.0'

}

Questo snippet di codice mostra come definire la dipendenza nel file del catalogo delle versioni:

[versions]
ktx = "1.9.0"

[libraries]
androidx-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "ktx" }

La denominazione consigliata per il blocco delle dipendenze nei cataloghi è dash-case (ad esempio androidx-ktx) per una migliore assistenza per il completamento del codice nei file di build.

Nel file build.gradle.kts di ogni modulo che richiede la dipendenza, definisci le dipendenze in base ai nomi definiti nel file TOML.

Kotlin

dependencies {
   implementation(libs.androidx.ktx)

}

Alla moda

dependencies {
   implementation libs.androidx.ktx

}

Esegui la migrazione dei plug-in

Aggiungi una voce per ogni plug-in sia nella sezione versions che nella sezione plugins del file libs.versions.toml. Sincronizza il progetto, quindi sostituisci le relative dichiarazioni nel blocco plugins{} dei file di build con i nomi del catalogo.

Questo snippet di codice mostra il file build.gradle.kts prima di rimuovere il plug-in:

Kotlin

// Top-level `build.gradle.kts` file
plugins {
   id("com.android.application") version "7.4.1" apply false

}

// Module-level `build.gradle.kts` file
plugins {
   id("com.android.application")

}

Alla moda

// Top-level `build.gradle` file
plugins {
   id 'com.android.application' version '7.4.1' apply false

}

// Module-level `build.gradle` file
plugins {
   id 'com.android.application'

}

Questo snippet di codice mostra come definire il plug-in nel file del catalogo delle versioni:

[versions]
androidGradlePlugin = "7.4.1"

[plugins]
android-application = { id = "com.android.application", version.ref = "androidGradlePlugin" }

Come per le dipendenze, la formattazione consigliata per le voci del catalogo dei blocchi plugins è dash-case (ad esempio android-application) per una migliore assistenza per il completamento del codice nei file di build.

Il seguente codice mostra come definire il plug-in com.android.application nei file build.gradle.kts di primo livello e a livello di modulo. Utilizza alias per i plug-in provenienti dal file del catalogo delle versioni e id per i plug-in non provenienti dal file del catalogo delle versioni, ad esempio i plug-in di convenzione.

Kotlin

// Top-level build.gradle.kts
plugins {
   alias(libs.plugins.android.application) apply false

}

// module build.gradle.kts
plugins {
   alias(libs.plugins.android.application)

}

Alla moda

// Top-level build.gradle
plugins {
   alias libs.plugins.android.application apply false

}

// module build.gradle
plugins {
   alias libs.plugins.android.application

}

Scopri di più

Per scoprire di più sulle opzioni aggiuntive per la configurazione del catalogo delle versioni, consulta queste risorse: