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

O repositório JCenter passou a ser somente leitura em 31 de março de 2021. Para saber mais, consulte a atualização do serviço JCenter.

O sistema de build do Android Studio é baseado no Gradle, e o Plug-in do Android para Gradle adiciona vários recursos específicos para criar apps Android. Embora o plug-in do Android normalmente seja atualizado com o Android Studio, o plug-in e o restante do sistema do Gradle podem ser executados e atualizados de forma independente.

Esta página explica como manter suas ferramentas do Gradle atualizadas e quais são as atualizações recentes. Para ver o que mudou, consulte as notas anteriores da versão do Plug-in do Android para Gradle.

Para ler um resumo detalhado das próximas alterações interruptivas no Plug-in do Android para Gradle, consulte o cronograma do plug-in.

Para saber como configurar seus builds do Android com o Gradle, consulte estas páginas:

Configurar seu build
Referência de DSL do Plug-in do Android para Gradle
Referência de DSL do Gradle (link em inglês)
Guia do usuário sobre a performance do Gradle (link em inglês)

Para saber mais sobre o sistema de build do Gradle, consulte o Guia do usuário do Gradle (em inglês).

Atualizar o Plug-in do Android para Gradle

Ao atualizar o Android Studio, talvez seja solicitado que você atualize automaticamente o Plug-in do Android para Gradle para a versão mais recente disponível. Você pode aceitar a atualização ou especificar manualmente uma versão com base nos requisitos de build do seu projeto.

Você pode especificar a versão do plug-in no menu File > Project Structure > Project no Android Studio ou no arquivo build.gradle do nível superior. A versão do plug-in se aplica a todos os módulos criados no projeto do Android Studio em questão. O exemplo abaixo define o plug-in para a versão 7.4.1 do arquivo build.gradle:

Groovy

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

Kotlin

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

Atenção: não use dependências dinâmicas em números de versão, por exemplo, 'com.android.tools.build:gradle:2.+'. O uso desse recurso pode resultar em atualizações inesperadas e dificuldades para resolver diferenças de versão.

Se a versão especificada do plug-in não tiver sido transferida por download, o Gradle vai fazer o download da próxima vez que você criar o projeto ou clicar em File > Sync Project with Gradle Files na barra de menus do Android Studio.

Atualizar o Gradle

Ao atualizar o Android Studio, você pode receber uma solicitação para também atualizar o Gradle para a versão mais recente disponível. Você pode aceitar a atualização ou especificar manualmente uma versão com base nos requisitos de build do projeto.

A tabela a seguir lista qual versão do Gradle é necessária para cada versão do Plug-in do Android para Gradle. Para ter a melhor performance, use a versão mais recente possível do Gradle e do plug-in.

Versão do plug-in	Versão mínima necessária do Gradle
8.1	8.0
8.0	8.0
7.4	7.5
7.3	7.4
7.2	7.3.3
7.1	7.2
7	7
4.2.0+	6.7.1

Versões anteriores

Versão do plug-in	Versão necessária do Gradle
4.1.0+	6.5+
4.0.0+	6.1.1+
3.6.0 - 3.6.4	5.6.4+
3.5.0 - 3.5.4	5.4.1+
3.4.0 - 3.4.3	5.1.1+
3.3.0 - 3.3.3	4.10.1+
3.2.0 - 3.2.1	4.6+
3.1.0+	4.4+
3.0.0+	4.1+
2.3.0+	3.3+
2.1.3 - 2.2.3	2.14.1 - 3.5
2.0.0 - 2.1.2	2.10 - 2.13
1.5.0	2.2.1 - 2.13
1.2.0 - 1.3.1	2.2.1 - 2.9
1.0.0 - 1.1.3	2.2.1 - 2.3

Você pode especificar a versão do Gradle no menu File > Project Structure > Project no Android Studio ou atualizar sua versão do Gradle usando a linha de comando. A maneira recomendada é usar a ferramenta de linha de comando Gradle Wrapper (link em inglês), que atualiza os scripts gradlew. O exemplo abaixo define a versão do Gradle como 7.5.1 usando o Gradle Wrapper. Execute esse comando duas vezes para fazer upgrade do Gradle e do próprio Gradle Wrapper. Para saber mais, consulte Como fazer upgrade do Gradle Wrapper (em inglês).

gradle wrapper --gradle-version 7.5.1

No entanto, esse processo pode falhar em alguns casos. Por exemplo, se você acabou de atualizar o Plug-in do Android para Gradle (AGP, na sigla em inglês) e ele não é mais compatível com a versão atual do Gradle. Nesse caso, é necessário editar a referência de distribuição do Gradle no arquivo gradle/wrapper/gradle-wrapper.properties. O exemplo abaixo define a versão do Gradle como 7.5.1 no arquivo gradle-wrapper.properties.

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

Plug-in do Android para Gradle e compatibilidade com o Android Studio

O sistema de build do Android Studio é baseado no Gradle, e o Plug-in do Android para Gradle adiciona vários recursos específicos para a criação de apps Android. A tabela abaixo lista qual versão do Plug-in do Android para Gradle é necessária para cada versão do Android Studio.

Versão do Android Studio	Versão do plug-in necessária
Giraffe \| 2022.3.1	3.2-8.1
Flamingo \| 2022.2.1	3.2-8.0
Electric Eel \| 2022.1.1	3.2-7.4
Dolphin \| 2021.3.1	3.2-7.3
Chipmunk \| 2021.2.1	3.2-7.2
Bumblebee \| 2021.1.1	3.2-7.1
Arctic Fox \| 2020.3.1	3.1-7.0

Para saber as novidades do Plug-in do Android para Gradle, acesse as notas da versão.

Mudanças do controle de versões (novembro de 2020)

Estamos atualizando o número da versão do Plug-in do Android para Gradle (AGP, na sigla em inglês) para melhorar a integração com a ferramenta de build do Gradle.

Confira as principais mudanças:

O AGP agora usa um controle de versões semântico, e as alterações interruptivas são direcionadas para versões principais.
Haverá uma versão principal do AGP lançada por ano, alinhada à versão principal do Gradle.
Após o AGP 4.2, virá a versão 7.0, que exige um upgrade para o Gradle versão 7.x. Cada vez que uma versão do AGP com mudanças significativas é liberada, um upgrade de versão significativo na ferramenta Gradle se faz necessário.
O uso das APIs vai ser descontinuado com aproximadamente um ano de antecedência, e os novos recursos serão lançados nesse mesmo tempo. As APIs descontinuadas vão ser removidas cerca de um ano depois, quando houver uma atualização de larga escala.

7.4.0 (dezembro de 2022)

O Plug-in do Android para Gradle 7.4.0 é uma versão principal que inclui vários novos recursos e melhorias.

Compatibilidade

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

Versões de patch

Confira abaixo uma lista das versões de patch do Plug-in do Android para Gradle 7.4.

Plug-in do Android para Gradle 7.4.2 (fevereiro de 2023)

Esta atualização secundária inclui as seguintes correções de bugs:

Problemas corrigidos
Problema 266780231 O DexingFileDependenciesTask.outputKeepRules é um diretório, mas está marcado como um OutputFile.
Problema 247906487 Erro `AnnotationProcessorOptions.arguments are queried` ao atualizar para a versão 7.4 Beta 1.
Problema 266967487 O processDebugUnitTestManifest falha com marcadores de posição de manifesto para variantes de teste.

Plug-in do Android para Gradle 7.4.1 (fevereiro de 2023)

Esta atualização secundária inclui as seguintes correções de bugs:

Problemas corrigidos
Problema 242831042 Migração da propriedade `destination` para a propriedade `outputLocation` para lidar com o aviso de descontinuação e se preparar para o Gradle 9.0
Problema 261329823 O AGP 7.4.0-rc01 interrompe a API Variant com a mensagem de erro "Querying the mapped value of `map(provider(java.util.Set))` before task '…' has completed is not supported" (Não há suporte para consultas ao valor mapeado de `map(provider(java.util.Set))` antes da tarefa '…')

Relatório pós-upgrade do assistente de upgrade do AGP e funcionalidade de reversão

O Assistente de upgrade do AGP agora inclui um relatório pós-upgrade. Esse relatório descreve as etapas que foram concluídas e informa se o upgrade foi concluído ou não. Ele também inclui uma ação para reverter mudanças feitas pelo assistente de upgrade, caso haja problemas para criar ou testar o projeto após o upgrade.

A importação do projeto é executada em paralelo

O ambiente de desenvolvimento integrado do Studio agora importa projetos em paralelo quando você usa o Gradle 7.4.2 ou mais recente e o Plug-in do Android para Gradle 7.2.0 ou mais recente. Especificamente, quando o Android Studio aciona uma sincronização do Gradle, as informações que descrevem os projetos incluídos no build são criadas em paralelo. Isso geralmente acelera o processo de sincronização, principalmente em projetos maiores. Os comparativos de mercado mostram que o tempo necessário para criar modelos do Gradle para um projeto muito grande (com 3.500 subprojetos do Gradle) é reduzido em 50%, de 10 para 5 minutos.

O Plug-in do Android para Gradle é voltado ao bytecode da JVM 11

A partir do Plug-in do Android para Gradle 7.4.0-alpha04, o AGP é enviado com o bytecode da JVM 11. Isso significa que, se você compilar no AGP ou programar verificações de lint personalizadas, será necessário voltar a versão para o bytecode da JVM 11. Uma das maneiras de fazer isso é incluir o seguinte no seu arquivo build.gradle do módulo:

sourceCompatibility = "11"
targetCompatibility = "11"