Usar o Assistente de upgrade do Plug-in do Android para Gradle

O Assistente de upgrade do Plug-in do Android do Gradle (AGP, na sigla em inglês) é uma ferramenta do Android Studio que ajuda você a fazer upgrade da versão do AGP usada pelo seu projeto.

Lançamos regularmente atualizações para o AGP relacionadas a novos recursos para configurar seu build, novas APIs usadas por outros plug-ins do Gradle e refinamento da integração do build do projeto com o Android Studio. Fazer upgrade da versão do AGP usada pelo seu projeto permite que você aproveite os recursos mais recentes.

Para que serve o Assistente de upgrade do AGP?

O Assistente de upgrade do AGP ajuda a orientar você sobre as mudanças necessárias para fazer upgrade das versões do AGP. Veja a seguir os casos de uso mais comuns do Assistente de upgrade:

  • Mudanças de sintaxe: o Assistente de upgrade tenta traduzir seus arquivos de build atuais de uma versão mais antiga do AGP para os necessários para uma versão mais recente dele. À medida que desenvolvemos o AGP, atualizamos os arquivos de build para que tenham suporte às interfaces conforme elas são substituídas, descontinuadas ou ficam sem suporte.

  • Requisitos de compatibilidade entre o AGP e o Gradle: o Assistente de upgrade reconhece os requisitos de compatibilidade entre o AGP e o Gradle e ajuda a garantir que você esteja usando a versão do Gradle necessária para a versão do AGP.

  • Requisitos de compatibilidade entre o AGP e plug-ins do Gradle de terceiros: o Assistente de upgrade reconhece os requisitos de compatibilidade entre o AGP e alguns plug-ins do Gradle de terceiros e ajuda a garantir que você esteja usando as versões necessárias dos plug-ins de terceiros para sua versão do AGP.

De modo geral, o objetivo do Assistente de upgrade é eliminar algumas das necessidades de mudanças por tentativa e erro para arquivos de build ou adivinhar o significado das mensagens de erro após o upgrade, além de explicar por que as mudanças propostas são necessárias.

Como usar o Assistente de upgrade do AGP

Para usar o Assistente de upgrade, confira se a estrutura do projeto o acomoda e execute no Android Studio, conforme descrito abaixo.

Configurar

Antes de executar o Assistente de upgrade, confira se o projeto está formatado corretamente e salvo em backup.

Estruturar o projeto usando arquivos de build do Gradle e linguagem específica do domínio

O Assistente de upgrade do AGP terá mais chances de funcionar se você fizer o seguinte:

  • Configurar o build usando os arquivos de build do Gradle: o Assistente de upgrade depende da análise estática dos arquivos de build do Gradle. Para aproveitar ao máximo o Assistente de upgrade, configure seu build usando esses arquivos. Observe que o Assistente de upgrade não oferece suporte a projetos que usam o buildSrc para definir constantes e variáveis usadas nos arquivos de build. De modo geral, não recomendamos o uso do buildSrc para estruturar seu projeto, porque ele pode ser ineficiente: qualquer mudança nas constantes e variáveis do buildSrc, sendo pequenas ou não, aciona uma recriação completa do projeto.
  • Usar a linguagem declarativa para build específica do domínio: os arquivos de build do Gradle são expressos em linguagens de programação completas (Groovy e/ou Kotlin). No entanto, quanto mais declarativa for a expressão da configuração do projeto, maior será a probabilidade de o Assistente de upgrade encontrar todos os lugares que precisam de ajuste para um upgrade.

Mesmo que um projeto não seja executado de acordo com essas limitações, é possível que o Assistente de upgrade ainda não realize um upgrade limpo. Consulte a seção Solução de problemas para ver como resolver ou informar bugs.

Fazer backup do projeto

Antes de começar a usar o Assistente de upgrade, recomendamos que seu projeto não tenha mudanças não confirmadas, conforme visto pelo seu sistema de controle de versões. Se você não estiver usando o controle de versão, sugerimos fazer backup da última versão válida conhecida.

Depois que o Assistente de upgrade for executado e o projeto for criado e testado, você poderá confirmar a nova versão do projeto no sistema de controle de versões.

Executar o Assistente de upgrade

Para executar o Assistente de upgrade, siga estas etapas:

  1. Inicie o Assistente de upgrade pelo prompt de notificação ou navegando até Tools > AGP Upgrade Assistant… A janela de ferramentas aberta mostra os detalhes do upgrade padrão da versão atual do AGP do projeto para a mais recente compatível com essa versão do Android Studio.
A janela da ferramenta Assistente de upgrade do AGP iniciada e o prompt de notificação.
Figura 1. A janela da ferramenta Assistente de upgrade do AGP iniciada e o prompt de notificação.
  1. Confira as etapas obrigatórias e as recomendadas. No painel à esquerda, há uma árvore com caixas de seleção que detalham etapas individuais no upgrade, categorizadas entre obrigatórias e recomendadas para atualização e informando se elas são pré-requisito de outras etapas ou não. Selecione itens individuais na árvore para ver mais detalhes sobre cada etapa no painel principal.

  2. Execute o upgrade selecionando as etapas obrigatórias ou desejadas e clicando em Run selected steps. O Assistente de upgrade faz mudanças nos arquivos de build do projeto e tenta sincronizar a nova build com o Android Studio. Isso pode demorar um pouco se você tiver vários módulos, já que pode ser necessário fazer o download de novas versões de plug-ins e bibliotecas.

  3. Depois que o projeto for sincronizado com o Android Studio, crie o projeto e execute pacotes de teste para verificar se a operação de upgrade não mudou nenhuma funcionalidade.

  4. Depois de verificar se o projeto está em bom estado, confirme a nova versão do projeto no sistema de controle de versões.

Solução de problemas

Se o Assistente de upgrade oferecer um upgrade, mas ele falhar (normalmente fazendo mudanças nos arquivos de build que resultam em uma falha de sincronização), há etapas que você pode seguir para isolar e corrigir o erro.

  • Primeiro, inspecione o erro que causou a falha na sincronização. Às vezes, ele tem uma causa clara que você pode resolver nos arquivos de build do projeto.

  • Se a mensagem de erro não estiver clara ou se a causa do problema não for óbvia, é hora de retornar o projeto ao estado original para dividir o upgrade em etapas menores. Restaure o estado original pelo controle de versões ou por backups e confira se o projeto (no estado original) está novamente sincronizado com o Android Studio. Depois, você pode investigar usando estes dois tipos de detalhamento de upgrade:

    • Faça upgrade para uma versão do AGP que não seja a mais recente. Se o upgrade que deu errado foi um de muitas versões, a melhor maneira de progredir e ajudar a isolar o problema é fazendo uma série de upgrades menores, uma versão de cada vez, para encontrar o primeiro upgrade que aciona o problema.
    • Em um upgrade, realize uma etapa por vez. Depois de encontrar um upgrade entre versões sucessivas do AGP que aciona o problema, talvez seja possível desativar etapas individuais nele. Se for, tente executar cada etapa, uma de cada vez, para descobrir qual delas é a responsável. Caso você não encontre a etapa responsável, confira as notas da versão de outros plug-ins do Gradle que você está usando para identificar problemas de compatibilidade com o Gradle ou o AGP. Às vezes, há uma nova versão para lidar com o uso de APIs descontinuadas ou internas.
  • Informe um bug. Às vezes, todas as etapas preparatórias e a sincronização são concluídas e a etapa final do upgrade ainda falha. Nesse caso, informe um bug.

Mesmo que você consiga corrigir o erro, informe a falha original ao rastreador de bugs para que a equipe de desenvolvimento possa resolver o problema.