Notas da versão da prévia do Plug-in do Android para Gradle

Esta página contém as notas da versão para prévias do Plug-in do Android para Gradle (AGP, na sigla em inglês).

Plug-in do Android para Gradle 9.0

O Plug-in do Android para Gradle 9.0 é uma nova versão principal da AGP que traz mudanças de API e comportamento.

Para atualizar para o Plug-in do Android para Gradle 9.0.0-alpha10, use o Assistente de upgrade do Plug-in do Android para Gradle no Android Studio Otter | 2025.2.1.

O assistente de upgrade do AGP ajuda a preservar os comportamentos atuais ao fazer upgrade do projeto quando apropriado. Assim, é possível fazer upgrade do projeto para usar o AGP 9.0, mesmo que você não esteja pronto para adotar todos os novos padrões do AGP 9.0.

Compatibilidade

O nível máximo da API Android compatível com o plug-in do Android para Gradle 9.0.0-alpha10 é o nível 36.

O plug-in do Android para Gradle 9.0.0-alpha10 exige o Gradle 9.0.0.

Versão mínima Versão padrão Observações
Gradle 9.0.0 9.0.0 Para saber mais, consulte Como atualizar o Gradle.
Ferramentas de build do SDK 36.0.0 36.0.0 Instale ou configure as Ferramentas de build do SDK.
NDK N/A 28.2.13676358 Instale ou configure uma versão diferente do NDK.
JDK 17 17 Para saber mais, consulte Como configurar a versão do JDK.

As classes DSL android agora implementam apenas as novas interfaces públicas.

Nos últimos anos, apresentamos novas interfaces para nossa DSL e API a fim de controlar melhor quais APIs são públicas. As versões 7.x e 8.x do AGP ainda usavam os tipos de DSL antigos (por exemplo, BaseExtension), que também implementavam as novas interfaces públicas para manter a compatibilidade à medida que o trabalho progredia nas interfaces.

O AGP 9.0 usa exclusivamente nossas novas interfaces DSL, e as implementações mudaram para novos tipos totalmente ocultos. Essa mudança também remove o acesso à API Variant antiga e descontinuada.

Para atualizar para o AGP 9.0, talvez seja necessário fazer o seguinte:

  • Verifique se o projeto é compatível com o Kotlin integrado:o plug-in org.jetbrains.kotlin.android não é compatível com a nova DSL.

  • Mude os projetos do KMP para o plug-in de biblioteca do Android Gradle para KMP:usar o plug-in org.jetbrains.kotlin.multiplatform no mesmo subprojeto do Gradle que os plug-ins com.android.library e com.android.application não é compatível com a nova DSL.

  • Atualize seus arquivos de build:embora a mudança de interfaces tenha como objetivo manter a DSL o mais semelhante possível, pode haver algumas pequenas mudanças.

  • Atualize sua lógica de build personalizada para referenciar a nova DSL e API:substitua todas as referências à DSL interna pelas interfaces públicas da DSL. Na maioria dos casos, essa será uma substituição individual. Substitua qualquer uso da applicationVariants e APIs semelhantes pela nova API androidComponents. Isso pode ser mais complexo, já que a API androidComponents foi projetada para ser mais estável e manter os plug-ins compatíveis por mais tempo. Confira exemplos em Receitas do Gradle.

  • Atualize plug-ins de terceiros:alguns plug-ins de terceiros ainda podem depender de interfaces ou APIs que não são mais expostas. Migre para versões desses plug-ins que sejam compatíveis com o AGP 9.0.

A mudança para as novas interfaces DSL impede que plug-ins e scripts de build do Gradle usem várias APIs descontinuadas, incluindo:

API descontinuada no bloco android Função Substituição
applicationVariants,
libraryVariants,
testVariants e
unitTestVariants 		Pontos de extensão para plug-ins adicionarem novas funcionalidades ao AGP. Substitua por androidComponents.onVariants, por exemplo: 
androidComponents {
    onVariants() { variant ->
        variant.signingConfig
            .enableV1Signing.set(false)
    }
}
 Talvez não haja uma substituição direta para todas as APIs anteriores. Informe um problema se houver um caso de uso que não seja coberto pelas novas APIs de variantes.
variantFilter Permite desativar as variantes selecionadas. Substitua por androidComponents.beforeVariants, por exemplo: 
androidComponents {
    beforeVariants(
        selector()
            .withBuildType("debug")
            .withFlavor("color", "blue")
    ) { variantBuilder ->
        variantBuilder.enable = false
    }
  }
deviceProvider e
testServer 		Registro de ambientes de teste personalizados para executar testes em dispositivos e emuladores Android. Mude para Dispositivos gerenciados pelo Gradle.
sdkDirectory,
ndkDirectory,
bootClasspath,
adbExecutable, e
adbExe 		Usar vários componentes do SDK do Android para tarefas personalizadas. Mude para androidComponents.sdkComponents.
registerArtifactType,
registerBuildTypeSourceProvider,
registerProductFlavorSourceProvider,
registerJavaArtifact,
registerMultiFlavorSourceProvider, e
wrapJavaSourceSet		 A funcionalidade obsoleta está relacionada principalmente ao processamento de fontes geradas no Android Studio, que parou de funcionar no AGP 7.2.0. Não há substituição direta para essas APIs.

Se você atualizar para o AGP 9.0 e encontrar a seguinte mensagem de erro, isso significa que seu projeto ainda está fazendo referência a alguns dos tipos antigos:

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

Se você estiver bloqueado por plug-ins incompatíveis de terceiros, poderá desativar e recuperar as implementações antigas da DSL, bem como a API de variantes antiga. Ao fazer isso, as novas interfaces também ficam disponíveis, e você ainda pode atualizar sua própria lógica de build para a nova API. Para recusar, inclua esta linha no arquivo gradle.properties:

android.newDsl=false

Você também pode começar a fazer upgrade para as novas APIs antes de fazer upgrade para o AGP 9.0. As novas interfaces estão presentes em muitas versões do AGP. Por isso, é possível ter uma combinação de novas e antigas. A documentação de referência da API AGP mostra a superfície da API para cada versão do AGP e quando cada classe, método e campo foram adicionados.

Durante a fase Alfa 9.0, vamos entrar em contato com os autores de plug-ins para ajudar na adaptação e no lançamento de plug-ins totalmente compatíveis com os novos modos. Além disso, vamos melhorar o Assistente de upgrade do AGP no Android Studio para orientar você durante a migração.

Se você perceber que a nova DSL ou API Variant não tem recursos ou funcionalidades, registre um problema assim que possível.

Kotlin integrado

O Plug-in do Android para Gradle 9.0 inclui suporte integrado para compilação do Kotlin, substituindo o plug-in do Kotlin aplicado separadamente. Isso simplifica a integração com o AGP, evitando o uso das APIs descontinuadas e melhorando o desempenho em alguns casos.

O Plug-in do Android para Gradle 9.0 tem uma dependência de tempo de execução do plug-in do Kotlin para Gradle 2.2.10, que é a versão mínima necessária para o suporte integrado ao Kotlin.

O Kotlin integrado no AGP 9.0 oferece suporte total ao ambiente de desenvolvimento integrado do Android Studio para test-fixtures. Para testar isso, use o AGP 9.0.0-alpha07 ou uma versão mais recente.

É possível desativar o Kotlin integrado definindo android.builtInKotlin=false.

Se você desativou o Kotlin integrado e também precisa usar uma versão mais antiga do plug-in do Kotlin para Gradle, force o downgrade:

buildscript {
    dependencies {
        classpath("org.jetbrains.kotlin:kotlin-gradle-plugin") {
            version { strictly("2.0.0") } // or another version that you want to use
        }
    }
}

Mudanças de comportamento

O Plug-in do Android para Gradle 9.0 tem os seguintes novos comportamentos:

Comportamento Recomendação
O Plug-in do Android para Gradle 9.0 usa a versão r28c do NDK por padrão. Considere especificar explicitamente a versão do NDK que você quer usar.
Por padrão, o Plug-in do Android para Gradle 9.0 exige que os consumidores de uma biblioteca usem a mesma versão ou uma versão mais recente do SDK de compilação. Use o mesmo SDK de compilação ou uma versão mais recente ao consumir uma biblioteca. Se isso não for possível ou se você quiser dar mais tempo para os consumidores de uma biblioteca que você publica fazerem a troca, defina AarMetadata.minCompileSdk explicitamente.

A AGP 9.0 inclui atualizações nos padrões das seguintes propriedades do Gradle. Assim, você pode preservar o comportamento do AGP 8.13 ao fazer upgrade:

Propriedade Função Mudança do AGP 8.13 para o AGP 9.0 Recomendação
android.newDsl Use as novas interfaces DSL sem expor as implementações legadas do bloco android.
Isso também significa que a API de variantes legada, como android.applicationVariants não está mais acessível. 		false → true Para desativar, defina android.newDsl=false.
Quando todos os plug-ins e a lógica de build usados no projeto forem compatíveis, remova a recusa.
android.builtInKotlin Ativamos o suporte para compilar código Kotlin diretamente no plug-in do Android Gradle, sem o plug-in org.jetbrains.kotlin.android. false → true Adote o Kotlin integrado removendo o uso do plug-in org.jetbrains.kotlin.android, se possível. Caso contrário, desative a opção definindo android.builtInKotlin=false.
android.uniquePackageNames Garante que cada biblioteca tenha um nome de pacote diferente. false → true Especifique nomes de pacotes exclusivos para todas as bibliotecas no projeto. Se isso não for possível, desative a flag durante a migração.
android.dependency.useConstraints Controla o uso de restrições de dependência entre configurações.
O padrão no AGP 9.0 é false, que usa apenas restrições em testes de dispositivos de aplicativos (AndroidTest). Definir como true vai reverter para o comportamento da versão 8.13. 		true → false Não use restrições de dependência em todos os lugares, a menos que seja necessário. Aceitar o novo padrão dessa flag também ativa otimizações no processo de importação de projetos, o que reduz o tempo de importação para builds com muitos subprojetos de biblioteca Android.
aandroid.enableAppCompileTimeRClass Compile o código em aplicativos com uma classe R não final, alinhando a compilação do aplicativo com a da biblioteca.
Isso melhora a incrementalidade e abre caminho para futuras otimizações de performance no fluxo de processamento de recursos. 		false → true Muitos projetos podem adotar o novo comportamento sem mudanças na origem. Se os campos da classe R forem usados em qualquer lugar que exija uma constante, como casos de troca, refatore para usar instruções if encadeadas.
android.sdk.defaultTargetSdkToCompileSdkIfUnset Usa a versão do SDK de compilação como o valor padrão para a versão do SDK de destino em apps e testes.
Antes dessa mudança, a versão do SDK de destino era definida como padrão para a versão mínima do SDK. 		false → true Especifique explicitamente a versão do SDK de destino para apps e testes.
android.onlyEnableUnitTestForTheTestedBuildType Cria apenas componentes de teste de unidade para o tipo de build testado.
No projeto padrão, isso resulta em um único teste de unidade para depuração, enquanto o comportamento anterior era executar testes de unidade para depuração ou lançamento. 		false → true Se o projeto não exigir que os testes sejam executados para depuração e lançamento, não é necessário fazer mudanças.
android.proguard.failOnMissingFiles Falha no build com um erro se algum dos arquivos de manutenção especificados na DSL do AGP não existir no disco. Antes dessa mudança, erros de digitação em nomes de arquivos faziam com que os arquivos fossem ignorados silenciosamente. false → true Remover declarações inválidas de arquivos ProGuard
android.r8.optimizedResourceShrinking Permite que o R8 mantenha menos recursos do Android considerando classes e recursos do Android juntos. false → true Se as regras de retenção do projeto já estiverem completas, não será necessário fazer mudanças.
android.r8.strictFullModeForKeepRules Permite que o R8 mantenha menos ao não manter implicitamente o construtor padrão quando uma classe é mantida. Ou seja, -keep class A não implica mais -keep class A { <init>(); }
 false → true Se as regras de retenção do projeto já estiverem completas, não será necessário fazer mudanças.

Substitua -keep class A por -keep class A { <init>(); } nas regras de manutenção do projeto em todos os casos em que você precisa que o construtor padrão seja mantido.
android.defaults.buildfeatures.resvalues Ativa resValues em todos os subprojetos true → false Ative o resValues apenas nos subprojetos que precisam dele definindo o seguinte nos arquivos de build do Gradle desses projetos: 
android {
  buildFeatures {
    resValues = true
  }
}
android.defaults.buildfeatures.shaders Ativa a compilação de shader em todos os subprojetos. true → false Ative a compilação de sombreadores apenas nos subprojetos que contêm sombreadores a serem compilados definindo o seguinte nos arquivos de build do Gradle desses projetos: 
android {
  buildFeatures {
    shaders = true
  }
}
android.r8.proguardAndroidTxt.disallowed No AGP 9.0, getDefaultProguardFile() vai oferecer suporte apenas a proguard-android-optimize.txt em vez de proguard-android.txt. Isso evita o uso acidental da flag ­dontoptimize, que está incluída em proguard-android.txt. false → true Você pode especificar explicitamente ­dontoptimize em um proguardFile personalizado se quiser evitar a otimização, além de usar proguard-android-optimize.txt. Remova a flag ­dontoptimize desse arquivo, se possível, porque ela reduz os benefícios da otimização do R8. Caso contrário, desative a opção definindo android.r8.globalOptionsInConsumerRules.disallowed=false.
android.r8.globalOptionsInConsumerRules.disallowed A partir do AGP 9.0, a publicação de bibliotecas Android e módulos de recursos vai falhar se os arquivos de manutenção do consumidor tiverem configurações problemáticas do Proguard. Os arquivos de manutenção do consumidor que incluem opções globais, como ­dontoptimize ou ­dontobfuscate, só devem ser usados em módulos de aplicativos e podem reduzir os benefícios de otimização para usuários da biblioteca. A compilação do módulo de app Android vai ignorar silenciosamente essas opções globais se elas estiverem incorporadas em uma dependência pré-compilada (JAR ou AAR). Para saber quando isso acontece, verifique o arquivo configuration.txt (normalmente em um caminho como <app_module>/build/outputs/mapping/<build_variant>/configuration.txt) em busca de comentários como: # REMOVED CONSUMER RULE: ­dontoptimize false → true As bibliotecas publicadas precisam remover todas as regras incompatíveis. As bibliotecas internas precisam mover as regras incompatíveis, mas necessárias, para um proguardFile em um módulo de app. Para desativar, defina android.r8.globalOptionsInConsumerRules.disallowed=false. Quando todos os arquivos de retenção do consumidor estiverem compatíveis, remova a recusa.

Recursos removidos

O Plug-in do Android para Gradle 9.0 remove as seguintes funcionalidades:

DSL alterada

O Plug-in do Android para Gradle 9.0 tem as seguintes mudanças interruptivas na DSL:

  • A parametrização de CommonExtension foi removida.

    Por si só, essa é apenas uma mudança incompatível no nível da origem para ajudar a evitar futuras mudanças incompatíveis no nível da origem, mas também significa que os métodos de bloco precisam ser movidos de CommonExtension para ApplicationExtension, LibraryExension, DynamicFeatureExtension e TestExtension.

    Ao fazer upgrade do projeto para o AGP 9.0, refatore o código do plug-in do Gradle que usa esses parâmetros ou os métodos de bloqueio. Por exemplo, o plug-in a seguir é atualizado para remover o parâmetro de tipo e não depender dos métodos de bloco removidos:

    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)
        }
    }
}

    Para plug-ins que têm como destino um intervalo de versões do AGP, usar o getter diretamente é compatível com versões do AGP anteriores à 9.0.

DSL removida

O Plug-in do Android para Gradle 9.0 remove:

APIs removidas

O Plug-in do Android para Gradle 9.0 remove:

Propriedades do Gradle removidas

As seguintes propriedades do Gradle foram adicionadas inicialmente como formas de desativar globalmente recursos que estavam ativados por padrão.

Esses recursos foram desativados por padrão desde o AGP 8.0 ou versões anteriores. Ative esses recursos apenas nos subprojetos que os usam para uma build mais eficiente.

Propriedade Função Substituição
android.defaults.buildfeatures.aidl Ativa a compilação AIDL em todos os subprojetos. Ative a compilação do AIDL apenas nos subprojetos em que há fontes AIDL definindo a seguinte propriedade nos arquivos de build do Gradle desses projetos: 
android {
  buildFeatures {
    aidl = true
  }
}
 no arquivo de build do Gradle de cada subprojeto que contém fontes AIDL
android.defaults.buildfeatures.renderscript Ativa a compilação do RenderScript em todos os subprojetos. Ative a compilação do RenderScript apenas nos subprojetos em que há fontes do RenderScript definindo a seguinte propriedade nos arquivos de build do Gradle desses projetos: 
android {
  buildFeatures {
    renderScript = true
  }
}

Propriedades do Gradle aplicadas

O AGP 9.0 gera um erro se você definir as seguintes propriedades do Gradle.

O Assistente de upgrade do Plug-in do Android para Gradle não vai fazer upgrade de projetos para o AGP 9.0 que usam essas propriedades.

Propriedade Função
android.r8.integratedResourceShrinking A redução de recursos agora é sempre executada como parte do R8. A implementação anterior foi removida.

Problemas corrigidos

Plug-in do Android para Gradle 9.0.0-alpha10

Problemas corrigidos
Plug-in do Android para Gradle
extractNativeLibs e useEmbeddedDex não podem vir do manifesto.
Avisos do R8 no AGP 9.0.0-alpha09
Lint
O Kotlin integrado não adiciona .kotlin_module ao META-INF
O classpath do Lint contém classes duplicadas em versões diferentes.
A solução alternativa para substituir recursos particulares não está funcionando (tools:override = "true")

Plug-in do Android para Gradle 9.0.0-alpha09

Problemas corrigidos
Plug-in do Android para Gradle
O plug-in "legacy-kapt" ignora o processamento de anotações, ao contrário do "kotlin-kapt".
compileSdkSpec.minorApiLevel não está funcionando com SettingsExtension
[fused lib - public] A biblioteca combinada gerada não inclui fontes

Plug-in do Android para Gradle 9.0.0-alpha08

Problemas corrigidos
Nenhum problema público foi marcado como corrigido no AGP 9.0.0-alpha08.

Plug-in do Android para Gradle 9.0.0-alpha07

Problemas corrigidos
Plug-in do Android para Gradle
Uma build falha se houver tarefas de geração de código
Com `android.builtInKotlin=false`, `android.newDsl=false` e `android.enableLegacyVariantApi=false`, o uso do plug-in `kotlin-android` vai falhar com a mensagem "A API 'applicationVariants' está obsoleta".
O Kotlin integrado não resolve kotlin-stdlib sem versão quando kotlin.stdlib.default.dependency=false
O DexData abre um arquivo sem fechar, impedindo a limpeza
O AndroidSourceDirectorySet vai parar de estender PatternFilterable no AGP 9.0
Erro de fixture de teste em módulos somente de teste
Erro incorreto ao usar receptores de contexto em fixtures de teste
Erros incorretos do ambiente de desenvolvimento integrado para código Kotlin em testFixtures

Plug-in do Android para Gradle 9.0.0-alpha06

Problemas corrigidos
Plug-in do Android para Gradle
A nova DSL de otimização não cria configuration.txt por padrão
O AGP 8.13.0 não verifica o gráfico de navegação em um módulo.
O AGP usa a API Gradle descontinuada: notação de várias strings
Alertar usuários que tentam usar a biblioteca multidex legada com minSdkVersion >=21
Lint
A verificação Lint ChecksSdkIntAtLeast não verifica se o valor anotado está correto

Plug-in do Android para Gradle 9.0.0-alpha05

Problemas corrigidos
Plug-in do Android para Gradle
android.proguard.failOnMissingFiles não está funcionando para consumerProguardFiles.
Atualizar a dependência do plug-in do Kotlin para Gradle para 2.2.10
Criar KotlinJvmAndroidCompilation usando a API KGP
Modo de API explícita do Kotlin aplicado a fontes de teste
Lint
O Lint está mostrando o aviso "Não foi possível limpar os caches do K2"

Plug-in do Android para Gradle 9.0.0-alpha04

Problemas corrigidos
Plug-in do Android para Gradle
Mudar a versão padrão de origem/destino do Java do Java 8 para o Java 11 no AGP 9.0
Inverter o padrão android.useAndroidX para "true"
Melhor exceção ao aplicar o plug-in kapt com Kotlin integrado.
Lint
O Lint está mostrando o aviso "Não foi possível limpar os caches do K2"

Plug-in do Android para Gradle 9.0.0-alpha03

Problemas corrigidos
Plug-in do Android para Gradle
Quando "isIncludeAndroidResources" está ativado, "process{Variant}UnitTestManifest" não mescla usos de "tools:overrideLibrary" no AGP 8.12.0.
AGP causando avisos de descontinuação no Gradle para tarefas de teste da JVM
DependencyReportTask é incompatível com o cache de configuração.
Lint
Bug: a remoção de recursos não utilizados não remove as traduções deles e nem pergunta sobre isso

Plug-in do Android para Gradle 9.0.0-alpha02

Problemas corrigidos
Plug-in do Android para Gradle
Falha na build quando o arquivo ProGuard não existe
remove buildconfig defaults gradle.properties flags
Mudar o valor padrão de targetSdk do app para ser baseado em compileSdk em vez de minSdk

Plug-in do Android para Gradle 9.0.0-alpha01

Problemas corrigidos
Plug-in do Android para Gradle
Remoção de AndroidSourceSet.jni descontinuado no AGP 9.0
Remover Installation.installOptions() no AGP 9.0
Remoção de BuildType.isRenderscriptDebuggable no AGP 9.0.
Remover android.defaults.buildfeatures.renderscript
`com.android.kotlin.multiplatform.library` falha com dispositivos gerenciados pelo Gradle
Remover flags padrão de `android.defaults.buildfeatures.aidl` em gradle.properties