Notas da versão 8.3 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 para Gradle (AGP, na sigla em inglês) normalmente seja atualizado no Android Studio, o plug-in e o restante do sistema do Gradle podem ser executados de forma independente do Android Studio e atualizados separadamente.

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 conferir o que foi corrigido nessa versão do Plug-in do Android para Gradle, consulte os problemas fechados.

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:

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.kts 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 8.3.0 no arquivo build.gradle.kts:

Kotlin

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

Groovy

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

Cuidado:não use dependências dinâmicas em números de versão, como 'com.android.tools.build:gradle:8.3.+'. 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 fará o download dela na próxima vez que você criar seu 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-inVersão mínima necessária do Gradle
8.4 (Alfa)8.6-rc-1
8.38.4
8.28.2
8.18.0
8.08.0
7.47.5

Versões anteriores

Versão do plug-inVersão necessária do Gradle
7.37.4
7.27.3.3
7.17.2
77
4.2.0+6.7.1
4.1.0+6.5+
4.0.0+6.1.1+
3.6.0 - 3.6.45.6.4+
3.5.0 - 3.5.45.4.1+
3.4.0 - 3.4.35.1.1+
3.3.0 - 3.3.34.10.1+
3.2.0 - 3.2.14.6+
3.1.0+4.4+
3.0.0+4.1+
2.3.0+3.3+
2.1.3 - 2.2.32.14.1 - 3.5
2.0.0 - 2.1.22.10 - 2.13
1.5.02.2.1 - 2.13
1.2.0 - 1.3.12.2.1 - 2.9
1.0.0 - 1.1.32.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 8.3 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 8.3

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 8.3 no arquivo gradle-wrapper.properties.

...
distributionUrl = https\://services.gradle.org/distributions/gradle-8.3-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 (AGP, na sigla em inglês) adiciona vários recursos específicos para a criação de apps Android. A tabela abaixo lista qual versão do AGP é necessária para cada versão do Android Studio.

Versão do Android Studio Versão necessária do AGP
Águas-vivas | 2023.3.1 3,2 a 8,4
Iguana | 2023.2.1 3.2-8.3
Hedgehog | 2023.1.1 3.2-8.2
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

Versões anteriores

Versão do Android Studio Versão necessária do AGP
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 mais informações sobre as novidades do Plug-in do Android para Gradle, acesse as notas da versão.

Versões mínimas de ferramentas para um nível da API do Android

Há versões mínimas do Android Studio e do AGP que oferecem suporte a um nível específico da API. O uso de versões do Android Studio ou do AGP que são anteriores às exigidas pelo targetSdk ou compileSdk do projeto pode levar a problemas inesperados. Recomendamos usar as versões de pré-lançamento mais recentes do Android Studio e do AGP para trabalhar em projetos voltados para versões de pré-lançamento do SO Android. Além da versão estável, você também pode instalar versões de pré-lançamento do Android Studio.

As versões mínimas do Android Studio e do AGP são as seguintes:

Nível da API Versão mínima do Android Studio Versão mínima do AGP
Prévia do VanillaIceCream Águas-vivas | 2023.3.1 8.4
34 Hedgehog | 2023.1.1 8.1.1
33 Flamingo | 2022.2.1 7.2

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.

Compatibilidade

O nível máximo da API para o Plug-in do Android para Gradle 8.3 é o 34. Confira outras informações de compatibilidade:

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

Confira a seguir os novos recursos do Plug-in do Android para Gradle 8.3.

Suporte a catálogos de versões do Gradle

O Android Studio oferece suporte a catálogos de versões do Gradle baseados em TOML, um recurso que permite gerenciar dependências em um local central e compartilhar dependências entre módulos ou projetos. O Android Studio agora facilita a configuração de catálogos de versões usando sugestões do editor e integração com a caixa de diálogo Project Structure. Aprenda a configurar e configurar catálogos de versões do Gradle ou como migrar seu build para catálogos de versões.

Preenchimento automático de código e navegação

O Android Studio oferece preenchimento automático de código quando você está editando um catálogo de versões no formato de arquivo TOML ou adicionando uma dependência de um catálogo de versões a um arquivo de build. Para usar o preenchimento de código, pressione Ctrl + Espaço (Command + Espaço no macOS). Além disso, você pode navegar rapidamente de uma referência de dependência no arquivo build.gradle do app para onde ela é declarada no catálogo de versões, pressionando Ctrl+b (Command+b no macOS).

Preenchimento de código ao adicionar uma dependência

Integração com a caixa de diálogo "Project Structure"

Se o projeto usa um catálogo de versões definido no formato de arquivo TOML, você pode editar as variáveis definidas nele com a visualização Variables da caixa de diálogo Project Structure (File > Project Structure > Variables) no Android Studio. Para cada catálogo de versões, há um menu suspenso que lista as variáveis desse catálogo. Para editar uma variável, clique no valor dela e substitua. Quando você salva essas alterações, o arquivo TOML é atualizado de acordo.

Variáveis de um catálogo de versões na caixa de diálogo "Project Structure"

Você também pode atualizar dependências na visualização Dependencies da caixa de diálogo Project Structure (File > Project Structure > Dependencies). Para atualizar versões usando a caixa de diálogo Project Structure, navegue até o módulo e a dependência que você quer editar e atualize o campo Requested Version. Quando você salva essas alterações, o arquivo TOML é atualizado de acordo. Se a versão da dependência tiver sido definida usando uma variável, atualizar a versão diretamente dessa maneira substituirá a variável por um valor fixado no código. Esteja ciente de que a remoção de uma dependência de um arquivo de build, usando ou não a caixa de diálogo Project Structure, não remove a dependência do catálogo de versões.

Dependências de um catálogo de versões na caixa de diálogo "Project Structure"

Limitações e problemas conhecidos

Confira abaixo problemas ou limitações conhecidos com o suporte a catálogos de versões do Gradle no Android Studio.

  • Erro ao destacar declarações de alias do plug-in em arquivos de script Kotlin: quando você adiciona uma declaração de plug-in no formato alias(libs.plugins.example), o editor adiciona um sublinhado vermelho na parte libs. Esse é um problema conhecido no Gradle versões 8.0 e anteriores e será resolvido em uma versão futura do Gradle.

  • Compatibilidade do Android Studio apenas com catálogos de versões no formato TOML. Atualmente, o suporte para preenchimento de código, navegação e caixa de diálogo "Project Structure" do Android Studio só está disponível para catálogos de versões definidos no formato de arquivo TOML. No entanto, ainda é possível adicionar um catálogo de versões diretamente no arquivo settings.gradle e usar as dependências dele no projeto.

  • Sem suporte à navegação para arquivos de build KTS: a navegação para uma definição de dependência em um catálogo de versões usando Control + clique (Command + clique no macOS) ainda não tem suporte para arquivos de build criados usando o script Kotlin.

  • O Firebase Assistente adiciona dependências diretamente nos scripts de build: o Firebase Assistente adiciona dependências diretamente aos scripts de build, e não por meio de catálogos de versões.

  • A funcionalidade "Find usages" não tem suporte: ainda não há suporte para a localização de usos de uma variável de catálogo de versões em outros arquivos de build, esteja o arquivo no KTS ou no Groovy. Ou seja, usar Control + clique (Command + clique no macOS) em uma definição de variável em um catálogo de versões não leva aos arquivos de build em que a variável é usada.

  • A caixa de diálogo "Project Structure" no Android Studio mostra vários arquivos de catálogo se eles estiverem na pasta raiz gradle, mas não mostra catálogos para um build composto. Por exemplo, se você tiver dois arquivos de catálogo, um para o app e outro para um build composto, a caixa de diálogo "Project Structure" mostrará apenas o arquivo de catálogo do app. Você pode usar um build composto, mas é necessário editar o arquivo TOML diretamente.

Outros insights do SDK: problemas com a política

O Android Studio mostra avisos de lint nos arquivos build.gradle.kts e build.gradle e na caixa de diálogo Project Structure para SDKs públicos que têm violações da política do Google Play no SDK Index do Google Play. Atualize todas as dependências que violam as políticas do Google Play, já que essas violações podem impedir que você publique no Google Play Console no futuro. Os avisos de violação da política complementam os avisos de versão desatualizada mostrados pelo Android Studio.

Suporte à versão do compileSdk do Android Studio.

O Android Studio exibirá um aviso se o projeto usar uma compileSdk que não é compatível com a versão atual do Android Studio. Se disponível, ele também sugere mover para uma versão do Android Studio que ofereça suporte ao compileSdk usado pelo projeto. Não se esqueça de que o upgrade do Android Studio também pode exigir que você faça upgrade do AGP. O AGP também mostra um aviso na janela de ferramentas Build se o compileSdk usado pelo projeto não tem suporte da versão atual do AGP.

Mudanças no comportamento do lint

A partir do Plug-in do Android para Gradle 8.3.0-alpha02, ao executar o lint em um módulo, tarefas separadas de análise do lint são executadas para os componentes principais e de teste do módulo. O objetivo dessa mudança é melhorar o desempenho. Para reverter para o comportamento anterior, defina android.experimental.lint.analysisPerComponent=false no arquivo gradle.properties.