Note di rilascio del plug-in Android Gradle 8.3

Il repository JCenter è diventato di sola lettura dal 31 marzo 2021. Per maggiori informazioni, consulta Aggiornamento del servizio JCenter.

Il sistema di build di Android Studio è basato su Gradle e il plug-in Android Gradle aggiunge diverse funzionalità specifiche per la creazione di app per Android. Anche se il plug-in Android per Gradle (AGP) viene generalmente aggiornato in fase di blocco con Android Studio, il plug-in (e il resto del sistema Gradle) può essere eseguito indipendentemente da Android Studio ed essere aggiornato separatamente.

In questa pagina viene spiegato come mantenere aggiornati gli strumenti Gradle e quali sono le novità negli aggiornamenti recenti. Per le note di rilascio delle versioni precedenti del plug-in Android Gradle, consulta le note di rilascio precedenti.

Per scoprire le correzioni apportate in questa versione del plug-in Android per Gradle, consulta i problemi chiusi.

Per un riepilogo generale delle imminenti modifiche che interessano il plug-in Android per Gradle, consulta la Roadmap del plug-in Android Gradle.

Per maggiori dettagli su come configurare le build Android con Gradle, consulta le seguenti pagine:

Per ulteriori informazioni sul sistema di build Gradle, consulta la guida dell'utente di Gradle.

Aggiorna il plug-in Android per Gradle

Quando aggiorni Android Studio, potresti ricevere un messaggio che ti chiede di aggiornare automaticamente il plug-in Android per Gradle all'ultima versione disponibile. Puoi scegliere di accettare l'aggiornamento o specificare manualmente una versione in base ai requisiti di build del progetto.

Puoi specificare la versione del plug-in nel menu File > Struttura del progetto > Progetto in Android Studio oppure nel file build.gradle.kts di primo livello. La versione del plug-in si applica a tutti i moduli integrati nel progetto Android Studio. L'esempio seguente imposta il plug-in alla versione 8.3.0 dal file build.gradle.kts:

Kotlin

plugins {
    id("com.android.application") version "8.3.0" apply false
    id("com.android.library") version "8.3.0" apply false
    id("org.jetbrains.kotlin.android") version "1.9.22" apply false
}

trendy

plugins {
    id 'com.android.application' version '8.3.0' apply false
    id 'com.android.library' version '8.3.0' apply false
    id 'org.jetbrains.kotlin.android' version '1.9.22' apply false
}

Attenzione: non utilizzare dipendenze dinamiche nei numeri di versione, ad esempio 'com.android.tools.build:gradle:8.3.+'. L'uso di questa funzionalità può causare aggiornamenti di versione imprevisti e difficoltà a risolvere le differenze di versione.

Se la versione del plug-in specificata non è stata scaricata, Gradle la scarica alla successiva creazione del progetto o fai clic su File > Sincronizza progetto con i file Gradle dalla barra dei menu di Android Studio.

Aggiorna Gradle

Quando aggiorni Android Studio, potresti ricevere anche una richiesta di aggiornare Gradle all'ultima versione disponibile. Puoi scegliere di accettare l'aggiornamento o specificare manualmente una versione in base ai requisiti di build del tuo progetto.

Nella tabella seguente è indicata la versione di Gradle richiesta per ogni versione del plug-in Android per Gradle. Per ottenere le migliori prestazioni, devi utilizzare l'ultima versione possibile di Gradle e del plug-in.

Versione del plug-inVersione Gradle minima richiesta
8.4 (alpha)8,6-rc-1
8.38.4
8.28.2
8.1con Android 8.0
con Android 8.0con Android 8.0
7,47,5

Versioni precedenti

Versione del plug-inVersione Gradle richiesta
7,37,4
7,27.3.3
7.17,2
7,07,0
4.2.0 e oltre6.7.1
4.1.0 e versioni successivePiù di 6,5
4.0.0 e oltre6.1.1 e versioni successive
3.6.0 - 3.6.45.6.4 e versioni successive
3,5,0-3,5,45.4.1 e versioni successive
3.4.0 - 3.4.35.1.1 e versioni successive
3,3.0 - 3,3.34.10.1 e versioni successive
3.2.0 - 3.2.1Più di 4,6
3.1.0 e oltrePiù di 4,4
3.0.0 e oltrePiù di 4,1
2.3.0 e oltrePiù di 3,3
2.1.3 - 2.2.32.14.1 - 3,5
2.0.0 - 2.1.22,10 - 2,13
1,5,02.2.1 - 2,13
1.2.0 - 1.3.12,2,1-2,9
1,0,0 - 1,1,32.2.1 - 2.3

Puoi specificare la versione di Gradle nel menu File > Struttura del progetto > Progetto in Android Studio oppure aggiornare la versione di Gradle utilizzando la riga di comando. Il metodo preferito è utilizzare lo strumento a riga di comando Gradle Wrapper, che aggiorna gli script gradlew. L'esempio seguente imposta la versione Gradle a 8.3 utilizzando Gradle Wrapper. Tieni presente che devi eseguire questo comando due volte per eseguire l'upgrade sia di Gradle sia del wrapper Gradle (per ulteriori informazioni, consulta Upgrade del wrapper Gradle).

gradle wrapper --gradle-version 8.3

Tuttavia, in alcuni casi questa operazione potrebbe non riuscire, ad esempio se hai appena aggiornato AGP e non è più conforme all'attuale versione di Gradle. In questo caso, devi modificare il riferimento alla distribuzione Gradle nel file gradle/wrapper/gradle-wrapper.properties. L'esempio seguente imposta la versione Gradle su 8.3 nel file gradle-wrapper.properties.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.3-bin.zip
...

Compatibilità del plug-in Android Gradle e di Android Studio

Il sistema di build di Android Studio è basato su Gradle e il plug-in Android Gradle (AGP) aggiunge diverse funzionalità specifiche per la creazione di app per Android. Nella tabella seguente è indicata la versione di AGP richiesta per ogni versione di Android Studio.

Versione di Android Studio Versione AGP obbligatoria
Meduse | 1.3.2023 3,2-8,4
Iguana | 1/2/2023 3,2-8,3
Riccio | 1.1.2023 3,2-8,2
Giraffa | 1.3.2022 3,2-8,1
Fenicottero | 1.2.2022 3,2-8,0
Anguilla elettrica | 1.1.2022 3,2-7,4

Versioni precedenti

Versione di Android Studio Versione AGP obbligatoria
Delfino | 1.3.2021 3,2-7,3
Scoiattolo americano | 1/2/2021 3,2-7,2
Bombolo | 1.1.2021 3,2-7,1
Volpe artica | 2020.3.1 3,1-7,0

Per informazioni sulle novità del plug-in Android per Gradle, consulta le note di rilascio del plug-in Android per Gradle.

Versioni minime degli strumenti per il livello API Android

Esistono versioni minime di Android Studio e AGP che supportano un livello API specifico. L'utilizzo di versioni di Android Studio o AGP precedenti a quelle richieste dalle targetSdk o compileSdk del progetto potrebbe causare problemi imprevisti. Ti consigliamo di utilizzare l'ultima versione di anteprima di Android Studio e AGP per lavorare su progetti che hanno come target le versioni in anteprima del sistema operativo Android. Puoi installare versioni di anteprima di Android Studio oltre a una versione stabile.

Le versioni minime di Android Studio e AGP sono le seguenti:

Livello API Versione minima di Android Studio Versione AGP minima
Anteprima VanillaIceCream Meduse | 1.3.2023 8.4
34 Riccio | 1.1.2023 8.1.1
33 Fenicottero | 1.2.2022 7,2

Modifiche al controllo delle versioni (novembre 2020)

Stiamo aggiornando la numerazione delle versioni per il plug-in Android Gradle (AGP) in modo che corrisponda meglio allo strumento di creazione Gradle sottostante.

Ecco le modifiche più significative:

  • AGP ora utilizzerà il controllo delle versioni semantico e le modifiche che provocano errori avranno come target le release principali.

  • Ogni anno verrà rilasciata una versione principale di AGP, in linea con la release principale di Gradle.

  • La release dopo AGP 4.2 sarà la versione 7.0 e richiederà un upgrade a Gradle versione 7.x. Ogni release principale di AGP richiede un upgrade della versione principale nello strumento Gradle sottostante.

  • Le API verranno ritirate con circa un anno di anticipo e contemporaneamente saranno disponibili funzionalità di sostituzione. Le API deprecate verranno rimosse circa un anno dopo, durante il successivo aggiornamento principale.

Compatibilità

Il livello API massimo supportato dal plug-in Android Gradle 8.3 è il livello API 34. Ecco altre informazioni sulla compatibilità:

Versione minima Versione predefinita Notes
Gradle 8.4 8.4 Per scoprire di più, consulta la pagina sull'aggiornamento di Gradle.
Strumenti di creazione dell'SDK 34,0,0 34,0,0 Installa o configura gli strumenti di creazione dell'SDK.
NDK N/A 25.1.8937393 Installa o configura una versione diversa dell'NDK.
JDK 17 17 Per ulteriori informazioni, vedi Impostazione della versione JDK.

Di seguito sono riportate le nuove funzionalità del plug-in Android per Gradle 8.3.

Supporto per i cataloghi delle versioni Gradle

Android Studio supporta i catalogi delle versioni di Gradle basati su TOML, una funzionalità che consente di gestire le dipendenze in un'unica posizione centrale e di condividere le dipendenze tra moduli o progetti. Android Studio ora semplifica la configurazione dei cataloghi delle versioni tramite i suggerimenti dell'editor e l'integrazione con la finestra di dialogo Struttura del progetto. Scopri come impostare e configurare i cataloghi delle versioni Gradle o come eseguire la migrazione della build ai cataloghi delle versioni.

Completamento e navigazione del codice

Android Studio offre il completamento del codice quando modifichi un catalogo delle versioni nel formato file TOML o aggiungi una dipendenza da un catalogo delle versioni a un file di build. Per utilizzare il completamento del codice, premi Ctrl+Barra spaziatrice (Comando+Barra spaziatrice su macOS). Inoltre, puoi passare rapidamente da un riferimento alle dipendenze nel file build.gradle dell'app alla posizione in cui viene dichiarata nel catalogo delle versioni premendo Ctrl+b (Comando+b su macOS).

Completamento del codice durante l'aggiunta di una dipendenza

Integrazione con la finestra di dialogo Struttura del progetto

Se il progetto utilizza un catalogo delle versioni definito nel formato file TOML, puoi modificare le variabili definite nella finestra di dialogo Struttura del progetto nella vista Variabili (File > Struttura del progetto > Variabili) in Android Studio. Per ogni catalogo delle versioni, è presente un menu a discesa in cui sono elencate le variabili del catalogo. Per modificare una variabile, fai clic sul relativo valore e sovrascrivilo. Quando salvi queste modifiche, il file TOML viene aggiornato di conseguenza.

Variabili di un catalogo delle versioni nella finestra di dialogo Struttura del progetto

Puoi aggiornare le dipendenze anche nella visualizzazione Dipendenze della finestra di dialogo Struttura del progetto (File > Struttura del progetto > Dipendenze). Per aggiornare le versioni utilizzando la finestra di dialogo Struttura del progetto, vai al modulo e alla dipendenza che vuoi modificare, quindi aggiorna il campo Versione richiesta. Quando salvi queste modifiche, il file TOML viene aggiornato di conseguenza. Tieni presente che se la versione della dipendenza è stata definita utilizzando una variabile, l'aggiornamento diretto della versione in questo modo sostituisce la variabile con un valore impostato come hardcoded. Tieni inoltre presente che la rimozione di una dipendenza da un file di build, indipendentemente dal fatto che utilizzi o meno la finestra di dialogo Struttura del progetto, non rimuove la dipendenza dal catalogo delle versioni.

Dipendenze da un catalogo delle versioni nella finestra di dialogo Struttura del progetto

Problemi noti e limitazioni

Di seguito sono riportati i problemi noti o le limitazioni relative al supporto dei cataloghi delle versioni Gradle in Android Studio.

  • Errore durante l'evidenziazione delle dichiarazioni degli alias dei plug-in nei file di script Kotlin: quando aggiungi una dichiarazione del plug-in nel formato alias(libs.plugins.example), l'editor aggiunge una sottolineatura rossa sotto la parte libs. Si tratta di un problema noto nelle versioni Gradle 8.0 e precedenti che verrà risolto in una versione futura di Gradle.

  • Supporto solo di Android Studio per i cataloghi di versioni in formato TOML: al momento, le finestre di dialogo per completamento del codice, navigazione e struttura del progetto in Android Studio sono disponibili solo per i cataloghi di versioni definiti nel formato file TOML. Tuttavia, puoi comunque aggiungere un catalogo delle versioni direttamente nel file settings.gradle e utilizzarne le dipendenze nel progetto.

  • Navigazione per i file di build KTS non supportata: l'accesso a una definizione delle dipendenze in un catalogo di versioni mediante Ctrl e clic (Comando + clic su macOS) non è ancora supportata per i file di build scritti utilizzando lo script Kotlin.

  • L'Assistente Firebase aggiunge le dipendenze direttamente negli script di build: l'Assistente Firebase aggiunge le dipendenze direttamente agli script di build anziché tramite i cataloghi delle versioni.

  • Funzionalità "Trova utilizzi" non supportata: non è ancora possibile trovare gli utilizzi di una variabile di catalogo delle versioni in altri file di build, a prescindere dal fatto che il file di build sia in KTS o Groovy. In altre parole, l'uso di Ctrl+clic (Comando+clic su macOS) su una definizione di variabile in un catalogo delle versioni non indirizza ai file di build in cui viene utilizzata la variabile.

  • La finestra di dialogo Struttura del progetto in Android Studio mostra più file di catalogo se si trovano nella cartella gradle principale, ma non i cataloghi per una build composita. Ad esempio, se hai due file di catalogo (uno per l'app e uno per una build composita), la finestra di dialogo Struttura del progetto mostra solo il file di catalogo delle app. Puoi utilizzare una build composita, ma devi modificare direttamente il relativo file TOML.

Ulteriori approfondimenti sull'SDK: problemi relativi alle norme

Android Studio mostra avvisi lint nei file build.gradle.kts e build.gradle e nella finestra di dialogo della struttura del progetto per gli SDK pubblici con violazioni delle norme di Play nell'indice di Google Play SDK. Dovresti aggiornare eventuali dipendenze che violano le norme di Google Play, in quanto queste violazioni potrebbero impedirti di pubblicare su Google Play Console in futuro. Gli avvisi di violazione delle norme integrano gli avvisi di versione obsoleta visualizzati da Android Studio.

Supporto della versione compileSdk di Android Studio

Android Studio mostra un avviso se il progetto utilizza un compileSdk non supportato dalla versione corrente di Android Studio. Se disponibile, ti consigliamo anche di passare a una versione di Android Studio che supporti l'elemento compileSdk utilizzato dal tuo progetto. Tieni presente che l'upgrade di Android Studio potrebbe richiedere anche l'upgrade di AGP. AGP mostra anche un avviso nella finestra dello strumento Crea se il valore compileSdk utilizzato dal progetto non è supportato dalla versione corrente di AGP.

Modifiche al comportamento dei lint

A partire dal plug-in Android per Gradle 8.3.0-alpha02, quando si esegue lint su un modulo, vengono eseguite attività separate di analisi lint per i componenti principali e di test del modulo. Questa modifica ha lo scopo di migliorare il rendimento. Per ripristinare il comportamento precedente, imposta android.experimental.lint.analysisPerComponent=false nel file gradle.properties.

La riduzione esatta delle risorse è attivata per impostazione predefinita

La riduzione precisa delle risorse, che rimuove le voci inutilizzate dal file resources.arsc ed elimina i file delle risorse inutilizzati, è attiva per impostazione predefinita. Quando questa riduzione è abilitata, la tabella delle risorse viene ridotta e nell'APK sono incluse solo le voci della cartella res di riferimento.

Per disattivare la riduzione precisa delle risorse, imposta android.enableNewResourceShrinker.preciseShrinking su false nel file gradle.properties del tuo progetto.