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