Note di rilascio dell'anteprima del plug-in Android per Gradle

Questa pagina contiene le note di rilascio per le versioni di anteprima del plug-in Android Gradle (AGP).

Plug-in Android per Gradle 9.0

Il plug-in Android per Gradle 9.0 è una nuova versione principale di AGP e introduce modifiche al comportamento e alle API.

Per eseguire l'aggiornamento al plug-in Android per Gradle 9.0.0-beta04, utilizza l'assistente per l'upgrade del plug-in Android per Gradle in Android Studio Otter 3 Feature Drop | 2025.2.3.

L'assistente per l'upgrade di AGP consente di preservare i comportamenti esistenti durante l'upgrade del progetto, se appropriato, consentendoti di eseguire l'upgrade del progetto per utilizzare AGP 9.0, anche se non sei pronto ad adottare tutti i nuovi valori predefiniti di AGP 9.0.

Compatibilità

Il livello API Android massimo supportato dal plug-in Android per Gradle 9.0.0-beta04 è il livello API 36.

Il plug-in Android per Gradle 9.0.0-beta04 richiede Gradle 9.0.0.

Le classi android DSL ora implementano solo le nuove interfacce pubbliche

Negli ultimi anni abbiamo introdotto nuove interfacce per il nostro DSL e la nostra API per controllare meglio quali API sono pubbliche. Le versioni di AGP 7.x e 8.x utilizzavano ancora i vecchi tipi di DSL (ad esempio BaseExtension), che implementavano anche le nuove interfacce pubbliche, per mantenere la compatibilità man mano che il lavoro sulle interfacce avanzava.

AGP 9.0 utilizza esclusivamente le nostre nuove interfacce DSL e le implementazioni sono state modificate in nuovi tipi completamente nascosti. Inoltre, viene rimosso l'accesso alla vecchia API Variant deprecata.

Per eseguire l'aggiornamento ad AGP 9.0, potresti dover:

• Assicurati che il tuo progetto sia compatibile con Kotlin integrato: il plug-in org.jetbrains.kotlin.android non è compatibile con il nuovo DSL.

• Passa ai progetti KMP con il plug-in Android Gradle Library per KMP: l'utilizzo del plug-in org.jetbrains.kotlin.multiplatform nello stesso progetto secondario Gradle dei plug-in com.android.library e com.android.application non è compatibile con il nuovo DSL.

• Aggiorna i file di build: Sebbene la modifica delle interfacce sia pensata per mantenere la DSL il più simile possibile, potrebbero esserci alcune piccole modifiche.

• Aggiorna la logica di build personalizzata in modo che faccia riferimento alla nuova DSL e alla nuova API: Sostituisci tutti i riferimenti alla DSL interna con le interfacce DSL pubbliche. Nella maggior parte dei casi, si tratta di una sostituzione uno a uno. Sostituisci qualsiasi utilizzo di applicationVariants e API simili con la nuova API androidComponents. Questa operazione potrebbe essere più complessa, in quanto l'API androidComponents è progettata per essere più stabile e mantenere la compatibilità dei plug-in più a lungo. Consulta le nostre ricette Gradle per alcuni esempi.

• Aggiorna i plug-in di terze parti: alcuni plug-in di terze parti potrebbero ancora dipendere da interfacce o API non più esposte. Esegui la migrazione alle versioni di questi plug-in compatibili con AGP 9.0.

Il passaggio alle nuove interfacce DSL impedisce ai plug-in e agli script di build Gradle di utilizzare varie API ritirate, tra cui:

androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}

androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }

Se esegui l'aggiornamento ad AGP 9.0 e visualizzi il seguente messaggio di errore, significa che il tuo progetto fa ancora riferimento ad alcuni dei tipi precedenti:

java.lang.ClassCastException: class com.android.build.gradle.internal.dsl.ApplicationExtensionImpl$AgpDecorated_Decorated
cannot be cast to class com.android.build.gradle.BaseExtension

Se i plug-in di terze parti incompatibili ti bloccano, puoi disattivare le vecchie implementazioni per il DSL, nonché la vecchia API Variant. Durante questa operazione, sono disponibili anche le nuove interfacce e puoi comunque aggiornare la tua logica di build alla nuova API. Per effettuare la disattivazione, includi questa riga nel file gradle.properties:

android.newDsl=false

Puoi anche iniziare l'upgrade alle nuove API prima di eseguire l'upgrade ad AGP 9.0. Le nuove interfacce sono presenti in molte versioni di AGP, quindi puoi avere un mix di nuove e vecchie. La documentazione di riferimento dell'API AGP mostra la superficie dell'API per ogni versione di AGP e quando sono stati aggiunti ogni classe, metodo e campo.

Durante la fase alpha 9.0, contatteremo gli autori di plug-in per aiutarli ad adattare e rilasciare plug-in completamente compatibili con le nuove modalità e miglioreremo l'assistente per l'aggiornamento di AGP in Android Studio per guidarti nella migrazione.

Se riscontri che le nuove API DSL o Variant non dispongono di funzionalità o caratteristiche, segnala un problema il prima possibile.

Kotlin integrato

Il plug-in Android per Gradle 9.0 introduce il supporto integrato di Kotlin e lo attiva per impostazione predefinita. Ciò significa che non devi più applicare il plug-in org.jetbrains.kotlin.android (o kotlin-android) nei file di build per compilare i file sorgente Kotlin. In questo modo, l'integrazione di Kotlin con AGP viene semplificata, si evita l'utilizzo di API ritirate e, in alcuni casi, le prestazioni migliorano.

Pertanto, quando esegui l'upgrade del progetto ad AGP 9.0, devi anche eseguire la migrazione a Kotlin integrato o disattivarlo.

Puoi anche disattivare selettivamente il supporto Kotlin integrato per i progetti secondari Gradle che non hanno origini Kotlin.

Dipendenza di runtime dal plug-in Kotlin per Gradle

Per fornire il supporto Kotlin integrato, il plug-in Android per Gradle 9.0 ora ha una dipendenza di runtime dal plug-in Kotlin per Gradle (KGP) 2.2.10. Ciò significa che non devi più dichiarare una versione di KGP e, se utilizzi una versione di KGP inferiore alla 2.2.10, Gradle eseguirà automaticamente l'upgrade alla versione 2.2.10. Allo stesso modo, se utilizzi una versione di KSP precedente alla 2.2.10-2.0.2, AGP la aggiornerà alla versione 2.2.10-2.0.2 in modo che corrisponda alla versione di KGP.

Esegui l'upgrade a una versione di KGP più recente

Per utilizzare una versione più recente di KGP o KSP, aggiungi quanto segue al file di build di primo livello:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:KGP_VERSION")

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin:KSP_VERSION")
    }
}

Eseguire il downgrade a una versione precedente di KGP

Puoi eseguire il downgrade della versione di KGP solo se hai disattivato Kotlin integrato. Questo perché AGP 9.0 attiva Kotlin integrato per impostazione predefinita e Kotlin integrato richiede KGP 2.2.10 o versioni successive.

Per utilizzare una versione precedente di KGP o KSP, dichiara la versione nel file di build di primo livello utilizzando una dichiarazione di versione esatta:

buildscript {
    dependencies {
        // For KGP
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("KGP_VERSION") }
        }

        // For KSP
        classpath("com.google.devtoolsksp:symbol-processing-gradle-plugin") {
            version { strictly("KSP_VERSION") }
        }
    }
}

Tieni presente che la versione minima di KGP a cui puoi eseguire il downgrade è la 2.0.0.

Supporto IDE per gli ambienti di test

AGP 9.0 offre il supporto completo dell'IDE Android Studio per gli ambienti di test.

Plug-in della libreria Fused

Il plug-in Fused Library (anteprima) ti consente di pubblicare più librerie come un unico AAR della libreria Android. In questo modo, gli utenti possono fare più facilmente affidamento sugli artefatti pubblicati.

Per informazioni su come iniziare, vedi Pubblicare più librerie Android come una sola con la libreria unita.

Modifiche al comportamento

Il plug-in Android per Gradle 9.0 ha i seguenti nuovi comportamenti:

AGP 9.0 include aggiornamenti ai valori predefiniti delle seguenti proprietà Gradle. In questo modo, durante l'upgrade puoi scegliere di mantenere il comportamento di AGP 8.13:

android {
  defaultConfig {
    testInstrumentationRunner = "..."
  }
}

android {
  buildFeatures {
    resValues = true
  }
}

android {
  buildFeatures {
    shaders = true
  }
}

Funzionalità rimosse

Il plug-in Android per Gradle 9.0 rimuove le seguenti funzionalità:

• Supporto delle app Wear OS incorporate
  AGP 9.0 rimuove il supporto per l'incorporamento delle app Wear OS, che non è più supportato in Google Play. Ciò include la rimozione delle configurazioni wearApp e della DSL AndroidSourceSet.wearAppConfigurationName. Consulta la pagina Distribuire su Wear OS per scoprire come pubblicare la tua app su Wear OS.
• androidDependencies e sourceSetsSegnala attività
• Supporto degli APK divisi basati sulla densità
  AGP 9.0 non supporta più la creazione di APK divisi basati sulla densità dello schermo. La funzionalità e le API correlate sono state rimosse. Per dividere gli APK in base alla densità dello schermo utilizzando AGP 9.0 o versioni successive, utilizza gli app bundle.

DSL modificato

Il plug-in Android per Gradle 9.0 presenta le seguenti modifiche DSL che causano interruzioni:

• La parametrizzazione di CommonExtension è stata rimossa.

  Di per sé, questa è solo una modifica che causa interruzioni a livello di origine per evitare future modifiche che causano interruzioni a livello di origine, ma significa anche che i metodi di blocco devono passare da CommonExtension a ApplicationExtension, LibraryExtension, DynamicFeatureExtension e TestExtension.

  Quando esegui l'upgrade del progetto ad AGP 9.0, esegui il refactoring del codice del plug-in Gradle che utilizza questi parametri o i metodi di blocco. Ad esempio, il seguente plug-in viene aggiornato per rimuovere il parametro type e non fare affidamento sui metodi di blocco rimossi:

  AGP 8.13

  val commonExtension: CommonExtension<*, *, *, *, *, *> =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig {
          minSdk {
              version = release(28)
          }
      }
  }
  

  AGP 9.0

  val commonExtension: CommonExtension =
          extensions.getByType(CommonExtension::class)
  commonExtension.apply {
      defaultConfig.apply {
          minSdk {
              version = release(28)
          }
      }
  }
  

  Per i plug-in che hanno come target un intervallo di versioni di AGP, l'utilizzo diretto del getter è compatibile a livello binario con le versioni di AGP precedenti alla 9.0.

DSL rimossa

Il plug-in Android per Gradle 9.0 rimuove:

• AndroidSourceSet.jni, perché non era funzionante.

• AndroidSourceSet.wearAppConfigurationName, in quanto riguarda il supporto delle app Wear OS incorporate rimosso.

• BuildType.isRenderscriptDebuggable, perché non era funzionante.

• DependencyVariantSelection. È sostituito da DependencySelection, che è esposto come kotlin.android.localDependencySelection

• Installation.installOptions(String). È sostituito dalla proprietà modificabile di Installation.installOptions.

• Il blocco sperimentale, ma mai stabilizzato PostProcessing.

• ProductFlavor.setDimension, che viene sostituita dalla proprietà dimension

• LanguageSplitOptions, che era utile solo per Google Play Instant, che è ritirato.

• DensitySplit, perché la funzionalità non è più supportata. La sostituzione prevede l'utilizzo di App Bundle.

API rimosse

Il plug-in Android per Gradle 9.0 rimuove:

• AndroidComponentsExtension.finalizeDSl. È sostituito da finalizeDsl

• Component.transformClassesWith. È sostituito da Instrumentation.transformClassesWith

• Component.setAsmFramesComputationMode. È sostituito da Instrumentation.setAsmFramesComputationMode

• ComponentBuilder.enabled. È sostituito da ComponentBuilder.enable.

• DependenciesInfoBuilder.includedInApk. È sostituito da includeInApk

• DependenciesInfoBuilder.includedInBundle. È sostituito da includeInBundle

• GeneratesApk.targetSdkVersion. È sostituito da targetSdk

• Variant.minSdkVersion. È sostituito da minSdk

• Variant.maxSdkVersion. È sostituito da maxSdk

• Variant.targetSdkVersion. È sostituito da targetSdk

• Variant.unitTest, in quanto non era applicabile al plug-in com.android.test. unitTest è disponibile sui sottotipi VariantBuilder che estendono HasUnitTest.

• VariantBuilder.targetSdk e targetSdkPreview, in quanto non erano significativi nelle raccolte. Utilizza GeneratesApkBuilder.targetSdk o GeneratesApkBuilder.targetSdkPreview in alternativa.

• VariantBuilder.enableUnitTest, in quanto non era applicabile al plug-in com.android.test. enableUnitTest è disponibile sui sottotipi VariantBuilder che estendono HasUnitTestBuilder.

• VariantBuilder.unitTestEnabled viene rimosso a favore di enableUnitTest, che ha un nome più coerente nei sottotipi VariantBuilder che estendono HasUnitTestBuilder.

• VariantOutput.enable. È sostituito da enabled

• FeaturePlugin e FeatureExtension deprecati e disabilitati.

• Le API BaseExtension.registerTransform deprecate e disattivate, che sono rimaste solo per consentire la compilazione in base all'ultima versione di AGP durante il targeting dell'esecuzione su AGP 4.2 o versioni precedenti.

Proprietà Gradle rimosse

Le seguenti proprietà Gradle sono state inizialmente aggiunte come modi per disattivare globalmente le funzionalità abilitate per impostazione predefinita.

Queste funzionalità sono disattivate per impostazione predefinita a partire da AGP 8.0 o versioni precedenti. Attiva queste funzionalità solo nei sottoprogetti che le utilizzano per una compilazione più efficiente.

android {
  buildFeatures {
    aidl = true
  }
}

android {
  buildFeatures {
    renderScript = true
  }
}

Proprietà Gradle applicate

AGP 9.0 genera un errore se imposti le seguenti proprietà Gradle.

L'assistente per l'upgrade del plug-in Android per Gradle non eseguirà l'upgrade dei progetti ad AGP 9.0 che utilizzano queste proprietà.

Problemi risolti

Plug-in Android per Gradle 9.0.0-beta04

Plug-in Android per Gradle 9.0.0-beta03

Plug-in Android per Gradle 9.0.0-beta02

Plug-in Android per Gradle 9.0.0-beta01

Plug-in Android per Gradle 9.0.0-alpha14

Plug-in Android per Gradle 9.0.0-alpha13

Plug-in Android per Gradle 9.0.0-alpha12

Plug-in Android per Gradle 9.0.0-alpha11

Plug-in Android per Gradle 9.0.0-alpha10

Plug-in Android per Gradle 9.0.0-alpha09

Plug-in Android per Gradle 9.0.0-alpha08

Plug-in Android per Gradle 9.0.0-alpha07

Plug-in Android per Gradle 9.0.0-alpha06

Plug-in Android per Gradle 9.0.0-alpha05

Plug-in Android per Gradle 9.0.0-alpha04

Plug-in Android per Gradle 9.0.0-alpha03

Plug-in Android per Gradle 9.0.0-alpha02

Plug-in Android per Gradle 9.0.0-alpha01