Помощник по обновлению плагина Android Gradle (AGP) — это инструмент в Android Studio, который помогает вам обновить версию AGP, используемую вашим проектом.
Часто выходят выпуски изменений AGP, связанных с новыми функциями настройки вашей сборки, новыми API для использования другими плагинами Gradle и улучшениями интеграции сборки проекта с Android Studio. Обновление версии AGP, используемой в вашем проекте, позволит вам воспользоваться новейшими функциями.
Дополнительные сведения о рекомендуемой структуре проекта для Помощника по обновлению см. в разделе Настройка на этой странице.
Варианты использования помощника по обновлению AGP
Помощник по обновлению AGP проведет вас через изменения, необходимые для обновления версий AGP. Ниже приведены наиболее распространенные варианты использования Помощника по обновлению:
Изменения синтаксиса : Помощник по обновлению пытается преобразовать файлы сборки для более старой версии AGP в файлы, необходимые для более новой версии AGP. По мере разработки AGP файлы сборки обновляются для поддержки интерфейсов, которые со временем заменяются, устаревают или перестают поддерживаться.
Требования совместимости между AGP и Gradle . Помощник по обновлению знает о требованиях совместимости между AGP и Gradle и помогает убедиться, что вы используете версию Gradle, необходимую для вашей версии AGP.
Требования совместимости между AGP и сторонними плагинами Gradle . Помощник по обновлению знает о требованиях совместимости между AGP и некоторыми сторонними плагинами Gradle и помогает убедиться, что вы используете версии сторонних плагинов Gradle, необходимые для вашей версии. АГП.
В целом, Помощник по обновлению упрощает обновление файлов сборки и понимание соответствующих сообщений об ошибках после обновления AGP. Помощник по обновлению также объясняет, почему предложенные изменения необходимы.
Как использовать помощник по обновлению AGP
Чтобы использовать Помощник по обновлению, убедитесь, что структура вашего проекта поддерживает этот инструмент, а затем запустите его из Android Studio, как описано в разделе Запуск Помощника по обновлению .
Настройте свой проект
Прежде чем запускать Помощник по обновлению, убедитесь, что ваш проект правильно отформатирован и у него есть резервная копия. Чтобы убедиться, что помощник по обновлению AGP настроен правильно, прочтите следующие разделы.
Структурируйте свой проект, используя файлы сборки Gradle и язык, специфичный для предметной области.
Чтобы максимально эффективно использовать помощник по обновлению AGP, выполните следующие действия:
- Настройте сборку с помощью файлов сборки Gradle . Помощник по обновлению использует статический анализ файлов сборки Gradle. Чтобы максимально эффективно использовать помощник по обновлению, настройте свою сборку с помощью этих файлов сборки.
- Используйте декларативный язык сборки, специфичный для предметной области : файлы сборки Gradle выражаются в Groovy или Kotlin. Однако чем декларативнее выражение конфигурации проекта, тем больше вероятность того, что Помощник по обновлению успешно найдет все места, требующие корректировки для обновления.
Даже если проект соответствует этим ограничениям, Помощник по обновлению все равно может не выполнить чистое обновление. См. раздел «Устранение ошибок» , чтобы узнать, как устранить ошибки или сообщить о них.
Резервное копирование вашего проекта
Прежде чем использовать Помощник по обновлению, мы рекомендуем убедиться, что в вашем проекте нет незафиксированных изменений, видимых вашей системой контроля версий. Если вы не используете контроль версий, на этом этапе используйте резервную копию последней известной работоспособной версии.
После запуска Помощника по обновлению и успешной сборки и тестирования проекта вы можете передать новую версию проекта в свою систему контроля версий.
Запустите Помощник по обновлению
Чтобы запустить Помощник по обновлению, выполните следующие действия:
Чтобы запустить Помощник по обновлению, выберите «Инструменты» > «Помощник по обновлению AGP» или щелкните уведомление, как показано на рисунке 1.
В появившемся окне инструмента отображаются сведения об обновлении по умолчанию, включая текущую версию AGP проекта и последнюю версию, поддерживаемую этой версией Android Studio.
Рис. 1. Окно инструмента AGP Upgrade Assistant при запуске с уведомлением. Проверьте необходимые и рекомендуемые действия.
На левой панели в дереве с флажками показаны отдельные этапы обновления, сгруппированные по категориям в зависимости от того, являются ли они обязательными или рекомендуемыми для обновления, а также являются ли они предварительным условием для других шагов. Выберите отдельные элементы в дереве, чтобы отобразить более подробную информацию о каждом шаге на главной панели.
Чтобы запустить обновление, выберите необходимые и желаемые шаги и нажмите « Выполнить выбранные шаги» .
Помощник по обновлению изменяет файлы сборки проекта и пытается синхронизировать новую сборку проекта с Android Studio. Если у вас много модулей, это может занять некоторое время, так как может потребоваться загрузка новых версий плагинов и библиотек.
Просмотрите отчет после обновления. В этом отчете описываются шаги, которые были выполнены, а также указано, было ли обновление успешным или неудачным. Он также включает в себя действие по отмене изменений, внесенных помощником по обновлению, если после обновления возникли проблемы со сборкой или тестированием проекта.
После успешной синхронизации проекта с Android Studio соберите проект и запустите наборы тестов, чтобы убедиться, что операция обновления не изменила какие-либо функциональные возможности.
Убедившись, что ваш проект находится в хорошем состоянии, зафиксируйте новую версию проекта в своей системе контроля версий.
Устранение ошибок
Если помощник по обновлению предлагает обновление, но обновление завершается неудачей, это обычно является результатом внесения изменений в файлы сборки, что приводит к сбою синхронизации. Выполните следующие действия, чтобы локализовать и исправить ошибку:
Сначала проверьте ошибку, которая привела к сбою синхронизации. Иногда ошибка имеет четкую причину, которую можно устранить в файлах сборки проекта.
Если сообщение об ошибке неясно или неочевидно, что является причиной проблемы, верните проект в исходное состояние, чтобы разбить обновление на более мелкие этапы. Восстановите исходное состояние из системы контроля версий или из резервных копий и убедитесь, что проект находится в исходном состоянии и синхронизирован с Android Studio.
Исследуйте ошибку, выполнив следующие два вида сбоев обновления:
Обновите AGP до другой версии, которая не является последней. Если обновление, которое пошло не так, было обновлением большого количества версий, лучший способ изолировать проблему — выполнить серию небольших обновлений от версии к версии, чтобы найти первое обновление, которое вызывает проблему.
В рамках обновления выполняйте отдельные шаги по одному. Как только вы определите обновление, вызывающее проблему, возможно, можно будет отключить отдельные этапы обновления. Если возможно, попробуйте выполнить каждый шаг по одному, чтобы определить, какой из этих шагов вызывает ошибку. Если вы не можете найти соответствующий шаг, проверьте примечания к выпуску любых других плагинов Gradle, которые вы используете, на предмет проблем совместимости с Gradle или AGP. Иногда в новом выпуске рассматривается использование устаревших или внутренних API.
Сообщить об ошибке . Иногда все подготовительные этапы и синхронизация завершаются успешно, но последний этап обновления по-прежнему не удается. В этом случае сообщите об ошибке. Даже если вам удастся исправить ошибку самостоятельно, сообщите об исходной ошибке в систему отслеживания ошибок, чтобы команда разработчиков могла решить проблему.