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.
Há lançamentos frequentes de mudanças do AGP relacionadas a novos recursos para configurar o build, novas APIs usadas por outros plug-ins do Gradle e refinamentos para a integração da compilação do projeto com o Android Studio. O upgrade da versão do AGP usada pelo seu projeto permite que você aproveite os recursos mais recentes.
Para mais informações sobre a estrutura de projeto recomendada para o Assistente de upgrade, consulte a seção Configuração nesta página.
Casos de uso do Assistente de upgrade do AGP
O Assistente de upgrade do AGP orienta você nas 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 os arquivos de build de uma versão mais antiga do AGP para os necessários em uma versão mais recente dele. À medida que o AGP é desenvolvido, os arquivos de build são atualizados para oferecer suporte a 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 sua 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.
Em geral, o Assistente de upgrade facilita a atualização de arquivos de build e a compreensão de mensagens de erro relacionadas após um upgrade do AGP. O Assistente de upgrade também explica 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 acomoda a ferramenta e execute-a no Android Studio, conforme descrito em Executar o Assistente de upgrade.
Configurar seu projeto
Antes de executar o Assistente de upgrade, confira se o projeto está formatado corretamente e salvo em backup. Para garantir que o Assistente de upgrade do AGP esteja configurado corretamente, leia as seções a seguir.
Estruturar o projeto usando arquivos de build do Gradle e linguagem específica do domínio
Para aproveitar ao máximo o Assistente de upgrade do AGP, siga estas etapas:
- Configure 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.
- Use a linguagem declarativa para build específica do domínio: os arquivos de build do Gradle são expressos em Groovy ou Kotlin. No entanto, quanto mais declarativa a expressão da configuração do projeto, maior será a probabilidade do Assistente de upgrade encontrar todos os lugares que precisam de ajuste para um upgrade.
Mesmo que um projeto esteja em conformidade com essas limitações, o Assistente de upgrade ainda pode não realizar um upgrade limpo. Consulte a Solução de problemas para ver orientações sobre 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ões, use um 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:
Para iniciar o Assistente de upgrade, acesse Tools > AGP Upgrade Assistant ou clique no prompt de notificação, como mostrado na figura 1.
A janela de ferramentas mostrada mostra os detalhes do upgrade padrão, incluindo a versão atual do AGP do projeto e a mais recente com suporte a essa versão do Android Studio.
Figura 1. A janela de ferramentas do Assistente de upgrade do AGP iniciada com o prompt de notificação. Confira as etapas obrigatórias e as recomendadas.
No painel à esquerda, a árvore com caixas de seleção detalha as etapas individuais no upgrade, categorizadas de acordo com a necessidade ou recomendação de atualização e se elas são pré-requisito de outras etapas. Selecione itens individuais na árvore para ver mais detalhes sobre cada etapa no painel principal.
Para executar o upgrade, selecione as etapas obrigatórias e desejadas e clique em Executar etapas selecionadas.
O Assistente de upgrade muda os arquivos de build do projeto e tenta sincronizar o novo build com o Android Studio. Isso pode demorar um pouco se você tem vários módulos, já que pode ser necessário fazer o download de novas versões de plug-ins e bibliotecas.
Analise o relatório feito depois do upgrade. Esse relatório descreve as etapas que foram concluídas e se o upgrade foi realizado ou não. Também inclui uma ação para reverter as mudanças feitas pelo Assistente de upgrade se houver problemas para criar ou testar o projeto após o upgrade.
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.
Depois de verificar se o projeto está em bom estado, confirme a nova versão no sistema de controle de versões.
Resolver problemas
Se o Assistente de upgrade sugerir um upgrade, mas ele falhar, isso geralmente é resultado de mudanças nos arquivos de build, resultando em uma falha da sincronização. Siga estas etapas para ajudar a 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, retorne 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 está no estado original e sincronizado com o Android Studio.
Investigue o erro usando dois tipos de detalhamento do 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 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 o upgrade que aciona o problema, é possível desativar as etapas individuais nele. Tente executar cada etapa, uma de cada vez, para descobrir qual delas é responsável pelo erro. Se você não encontrar a etapa responsável, confira as notas da versão de qualquer outro plug-in do Gradle que você está usando para identificar problemas de compatibilidade com o Gradle ou AGP. Às vezes, uma nova versão aborda o uso de APIs descontinuadas ou internas.
Informar um bug. Às vezes, todas as etapas preparatórias e a sincronização são concluídas, mas 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 o problema possa ser resolvido pela equipe de desenvolvimento.