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