O Plug-in do Android para Gradle (AGP, na sigla em inglês) é o sistema de build compatível com apps Android e inclui suporte para compilar vários tipos diferentes de fontes e vinculá-las em um aplicativo que pode ser executado em um dispositivo Android físico ou um emulador.
A seção a seguir descreve a evolução planejada da DSL e da API do AGP. À medida que novas APIs forem introduzidas em versões estáveis, as APIs antigas serão marcadas como suspensas. Essas APIs suspensas ficarão indisponíveis na próxima versão estável. As seções a seguir fornecem informações sobre as próximas mudanças em cada versão principal do AGP.
Para ver um registro detalhado sobre as descontinuações ou remoções da API AGP, consulte as atualizações da API AGP.
AGP 10.0 (final de 2026)
Mudanças e modernização da API do Plug-in do Android para Gradle 10.0
O AGP 10.0 conclui a transição para um modelo de build totalmente lento e compatível com o cache de configuração. Esta versão é o resultado de um esforço de vários anos para substituir APIs legadas e não lentas por uma arquitetura mais segura e com melhor desempenho.
Por que um modelo de build lento?
No modelo de build legado e não lento, o Gradle avalia objetos, consulta dados de variantes e configura tarefas em todos os módulos do projeto durante cada sincronização ou invocação de build. Essa avaliação ansiosa desperdiça tempo de CPU e memória em variantes e tarefas que não estão em execução e causa conflitos de ordenação de avaliação em scripts de build complexos.
Ao fazer a transição para um modelo de build totalmente lento usando provedores lentos
(Provider<T>) e a API Variant moderna (androidComponents {}), as propriedades
e a fiação de tarefas são calculadas lentamente sob demanda, somente quando necessário pelo
gráfico de execução de build ativo.
As APIs legadas que estão sendo removidas nesta versão eram fundamentalmente incompatíveis com essa arquitetura moderna. A remoção delas permite que o AGP ofereça suporte total ao cache de configuração do Gradle e ao isolamento de projetos, o que melhora drasticamente as velocidades de build e os tempos de sincronização no Android Studio.
A principal diferença arquitetônica
A API BaseVariant legada (applicationVariants.all {}) era ansiosa e centrada em tarefas. Ela dava aos desenvolvedores acesso direto às tarefas do Gradle e às configurações internas durante a fase de configuração, o que inerentemente quebra os recursos modernos de desempenho do Gradle.
A nova API Variant (androidComponents {}) é lenta e centrada em artefatos. Ela
usa a API Property do Gradle de forma extensiva e remove completamente todas as referências a
Task e TaskProvider, exigindo que você interaja de forma limpa com entradas e
saídas (Variant.artifacts) em vez das próprias tarefas.
O que está sendo removido e substituído
Todas as interfaces e classes anteriores usadas na DSL legada e na antiga API Variant foram excluídas. Para preparar seus scripts de build e plug-ins personalizados, migre das seguintes APIs e flags de fim de vida útil:
| API ou recurso removido | Substituição ou ação necessária |
|---|---|
Acesso direto à tarefa:
|
API Artifacts:em vez de buscar a tarefa para
mudar o comportamento dela, use variant.artifacts para
anexar, modificar ou substituir arquivos reais (artefatos) que passam entre as
tarefas.
|
Registro de origem ansioso:
|
API Sources: conecte o diretório de saída da tarefa personalizada usando variant.sources.java.addGeneratedSourceDirectory(...).
|
Acesso ao caminho de classe / configuração:
|
API Instrumentation:para modificar ou inspecionar bytecode (o caso de uso mais comum para acesso ao caminho de classe), use variant.instrumentation.transformClassesWith(...) usando AsmClassVisitorFactory.
|
Mutação de propriedade ansiosa:
|
Instâncias `MapProperty` lentas: use
variant.buildConfigFields.put(...) e
variant.manifestPlaceholders.put(...).
|
Flags de desativação:
|
Sem substituição direta. Remova essas flags de
gradle.properties. A DSL moderna e o Kotlin integrado são
aplicados de forma estrita.
|
Extensões legadas da API Variant:
|
Substitua por androidComponents.onVariants(). |
Filtragem de variantes (bloco variantFilter) |
Substitua por androidComponents.beforeVariants() usando
seletores de variantes.
|
Componentes do SDK e do NDK:
|
Acesse os componentes do SDK usando
androidComponents.sdkComponents.
|
Ambientes de teste:
|
Migre o registro de dispositivos de teste personalizados para dispositivos gerenciados pelo Gradle. |
APIs de registro obsoletas:
|
Excluído sem substituição direta. |
| API Transform |
Substitua as transformações pela API Artifacts e
AsmClassVisitorFactory.
|
Para acessar todas as interfaces e classes da DSL de substituição e da API Variant (androidComponents {})
, sempre use o gradle-api
artefato ao desenvolver plug-ins personalizados do Gradle ou lógica de build.
Etapas da migração
Para ajudar a tornar o upgrade para o AGP 10.0 simples e previsível, siga estas práticas de migração:
- Execute o Assistente de upgrade do AGP: antes de fazer upgrade diretamente para a versão 10.0, execute
o Assistente de upgrade do AGP oficial no
Android Studio (
Tools > AGP Upgrade Assistant). Ele automatiza várias migrações comuns de DSL e scripts de build e ajuda a preservar os comportamentos de build atuais. - Use as habilidades do modo de agente no Android Studio: aproveite as habilidades de upgrade de IA (como as habilidades de upgrade do AGP disponíveis no repositório de habilidades do Android) para automatizar e simplificar a migração de lógicas de build e DSLs complexas no Android Studio.
- Corrija os avisos de suspensão no AGP 9.x primeiro:faça upgrade do projeto para a versão mais recente do AGP 9.x e resolva todos os avisos de suspensão atuais. Depois que o projeto funcionar com a versão 9.x sem avisos e sem depender de
android.newDsl=falseouandroid.builtInKotlin=false, a transição para a versão 10.0 será tranquila. - Audite plug-ins do Gradle de terceiros:verifique se os plug-ins de terceiros foram atualizados para versões compatíveis com o AGP 10.0. Os plug-ins que ainda dependem de tipos de extensão legados vão causar falhas de build, como
ClassCastException: ... cannot be cast to class BaseExtension. - Use receitas de migração oficiais: para exemplos de migração complexos e reais e comparações lado a lado, consulte o repositório oficial gradle-recipes do GitHub.
Confira abaixo uma comparação antes e depois mostrando como migrar de variantes legadas de consulta ansiosa para variantes de configuração lenta usando androidComponents {}:
Antes: API Variant legada (removida no AGP 10.0)
// Eager evaluation using the legacy Variant API
android {
applicationVariants.all { variant ->
if (variant.buildType.name == "release") {
// Eagerly queries and modifies properties during evaluation
}
}
}
Depois: API Variant moderna (androidComponents {})
// Lazy, Configuration Cache compatible Variant API
androidComponents {
onVariants(selector().withBuildType("release")) { variant ->
// Safely and lazily configures properties
}
}
Como testar o comportamento do AGP 10.0 no AGP 9.x
Não é necessário esperar o lançamento do AGP 10.0 para começar a testar os comportamentos de build e validar a compatibilidade. Ao executar qualquer versão do AGP 9.x, você pode aplicar explicitamente o comportamento do AGP 10.0 verificando se o gradle.properties desativa todas as desativações e define as seguintes flags de comportamento estritas:
# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true
# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true
Ao aplicar android.newDsl=true e android.builtInKotlin=true, você pode verificar se a lógica de build personalizada e os plug-ins de terceiros são totalmente compatíveis com os requisitos de API estritos do AGP 10.0.
Desativação seletiva de subprojetos durante a migração
Se você quiser ativar android.newDsl=true globalmente no projeto para testar comportamentos modernos, mas precisar de mais tempo para migrar subprojetos específicos, poderá desativar seletivamente módulos individuais a partir do AGP 9.4.0-alpha04.
Adicione android.newDsl.optOut a gradle.properties especificando os caminhos do projeto:
# Enable modern DSL globally across the build
android.newDsl=true
# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib
Desativação seletiva do Kotlin integrado por módulo
Se você quiser ativar o Kotlin integrado globalmente no projeto (android.builtInKotlin=true), mas precisar de mais tempo para migrar subprojetos específicos de kotlin-android (ou para módulos sem código Kotlin), configure esses módulos no nível da DSL em vez do nível do projeto. Defina enableKotlin = false no arquivo de build do módulo:
android {
enableKotlin = false
}
Fluxo de trabalho de feedback e relatório de bugs
Queremos garantir que a nova API Variant ofereça suporte aos seus casos de uso necessários. Se você encontrar um obstáculo ao migrar das APIs antigas em que a nova API Variant não pode acomodar seu caso de uso, siga estas etapas para enviar feedback:
- Verifique os itens atuais: primeiro, verifique o bug de rastreamento global da API Variant do AGP 10.0 para saber se o bloqueador de migração já é conhecido e clique em +1 no problema.
- Informe APIs ausentes: se o caso de uso for exclusivo, registre uma nova solicitação de recurso usando nosso modelo específico do AGP 10.0 para que possamos investigar e ajudar.
(Provisório) O acesso às classes internas particulares do AGP foi removido
A dependência do artefato gradle agora oculta todas as classes internas
e fornece acesso de compilação apenas às interfaces e classes
disponíveis no artefato gradle-api. Isso afeta a compilação do plug-in.
Não é possível adicionar manualmente uma dependência para ter acesso às classes internas.
AGP 9.0 (janeiro de 2026)
Novas APIs Variant estão estáveis, e as APIs antigas foram suspensas
As APIs Variant (link em inglês) que estavam em desenvolvimento nas versões 4.1 e 4.2 estão
estáveis e localizadas no artefato gradle-api. As
interfaces e classes anteriores usadas na antiga API Variant foram suspensas e exigem ativação explícita para uso.
Novas interfaces DSL estão estáveis, e as antigas foram suspensas
As interfaces DSL que estavam em desenvolvimento nas versões 4.1, 4.2 e
7.0 agora estão estáveis e localizadas no artefato gradle-api. As interfaces e classes usadas anteriormente na DSL foram suspensas e exigem
ativação explícita para uso.
Classes AGP internas particulares ainda acessíveis
As classes internas particulares do AGP, localizadas em outros artefatos, ainda podem ser acessadas durante a compilação de arquivos de build e plug-ins, mas não recomendamos usá-las porque elas podem mudar de maneiras inesperadas a qualquer momento.