Cronograma de migração da DSL/API do Plug-in do Android para Gradle

O Plug-in do Android para Gradle (AGP, na sigla em inglês) é o sistema de compilação compatível com apps Android e inclui compatibilidade 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 lazy 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 eficiente.

Por que um modelo de build lento?

No modelo de build legado e não lazy, 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 imediata desperdiça tempo de CPU e memória em variantes e tarefas que não estão em execução, além de causar 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 conexão de tarefas são computadas lentamente sob demanda somente quando necessário pelo gráfico de execução de build ativo.

As APIs legadas removidas nesta versão eram fundamentalmente incompatíveis com essa arquitetura moderna. A remoção 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 legada BaseVariant (applicationVariants.all {}) era ansiosa e centrada em tarefas. Ele dava aos desenvolvedores acesso direto a tarefas do Gradle e configurações internas durante a fase de configuração, o que prejudica inerentemente os recursos modernos de desempenho do Gradle.

A nova API Variant (androidComponents {}) é lenta e centrada em artefatos. Ela usa extensivamente a API Property do Gradle e remove completamente todas as referências a Task e TaskProvider, exigindo que você interaja de maneira limpa com entradas e saídas (Variant.artifacts) em vez das próprias tarefas.

O que será 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 da vida útil:

Para acessar todas as interfaces e classes de DSL e API Variant (androidComponents {}) de substituição, sempre use o artefato gradle-api ao desenvolver plug-ins personalizados do Gradle ou lógica de build.

Etapas da migração

Para facilitar e tornar previsível o upgrade para o AGP 10.0, siga estas práticas de migração:

1. 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 script de build e ajuda a preservar os comportamentos de build existentes.
2. Use habilidades do modo 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.
3. Primeiro, corrija os avisos de descontinuação no AGP 9.x:faça upgrade do projeto para a versão mais recente do AGP 9.x e resolva todos os avisos de descontinuação. Quando seu projeto funcionar com a versão 9.x sem avisos e sem depender de android.newDsl=false ou android.builtInKotlin=false, a migração para a versão 10.0 será uma transição tranquila.
4. 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 causam falhas de build, como ClassCastException: ... cannot be cast to class BaseExtension.
5. Use receitas de migração oficiais:para exemplos de migração complexos e do mundo real e comparações lado a lado, consulte o repositório do GitHub gradle-recipes (em inglês).

Confira uma comparação de antes e depois mostrando como migrar de variantes legadas de consulta 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 Modern Variant (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 é preciso 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 recusas e define as seguintes flags de comportamento estrito:

# 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 sua lógica de build personalizada e os plug-ins de terceiros são totalmente compatíveis com os requisitos rigorosos da API do AGP 10.0.

Desativação seletiva de subprojetos durante a migração

Se você quiser ativar o android.newDsl=true globalmente no projeto para testar comportamentos modernos, mas precisar de mais tempo para migrar subprojetos específicos, será possível desativar seletivamente módulos individuais a partir do AGP 9.4.0-alpha04. Adicione android.newDsl.optOut a gradle.properties especificando caminhos de 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 seu projeto (android.builtInKotlin=true), mas precisar de mais tempo para migrar subprojetos específicos do 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 seja compatível com os casos de uso necessários. Se você encontrar um obstáculo ao migrar das APIs antigas e a nova API Variant não atender ao seu caso de uso, siga estas etapas para enviar feedback:

1. Verifique os itens atuais:primeiro, confira o bug de rastreamento global da API de variantes do AGP 10.0 para saber se o bloqueador de migração já é conhecido e clique em +1 no problema.
2. Informar APIs ausentes:se o caso de uso for exclusivo, envie uma nova solicitação de recurso usando nosso modelo específico da API Variant 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 dá 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 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 descontinuadas e exigem ativação explícita para serem usadas.

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 serem usadas.

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 o uso delas porque podem mudar de maneiras inesperadas a qualquer momento.