Как использовать Ассистента по обновлению плагина Android Gradle

Помощник по обновлению плагина 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. Помощник по обновлению также объясняет, почему необходимы предлагаемые изменения.

Как использовать AGP Upgrade Assistant

Чтобы использовать Помощник по обновлению, убедитесь, что структура вашего проекта совместима с этим инструментом, а затем запустите его из Android Studio, как описано в разделе Запуск Помощника по обновлению.

Настройте проект

Перед запуском Помощника по обновлению убедитесь, что проект правильно отформатирован и у вас есть его резервная копия. Чтобы убедиться, что помощник по обновлению AGP настроен правильно, прочитайте следующие разделы.

Структурируйте проект с помощью файлов сборки Gradle и предметно-ориентированного языка.

Чтобы максимально эффективно использовать Помощник по обновлению AGP, сделайте следующее:

  • Настройте сборку с помощью файлов сборки Gradle. Помощник по обновлению использует статический анализ файлов сборки Gradle. Чтобы максимально эффективно использовать Помощник по обновлению, настройте сборку с помощью этих файлов. Используйте каталоги версий Gradle, чтобы ссылаться на зависимости и плагины, определенные в файле libs.versions.toml в подкаталоге gradle вашего проекта.
  • Используйте декларативный предметно-ориентированный язык сборки. Файлы сборки Gradle написаны на Groovy или Kotlin. Однако чем более декларативно выражена конфигурация проекта, тем выше вероятность того, что Помощник по обновлению успешно найдет все места, требующие корректировки для обновления.

Даже если проект соответствует этим ограничениям, Помощник по обновлению все равно может не выполнить чистое обновление. Инструкции по устранению ошибок и отправке сообщений о них приведены в разделе Устранение неполадок.

Как создать резервную копию проекта

Перед использованием Помощника по обновлению рекомендуем убедиться, что в вашем проекте нет незафиксированных изменений, которые видны в системе управления версиями. Если вы не используете управление версиями, используйте резервную копию последней известной рабочей версии.

После того как Помощник по обновлению завершит работу, а проект будет успешно собран и протестирован, вы можете зафиксировать новую версию проекта в системе управления версиями.

Запустите Помощник по обновлению

Чтобы запустить Помощник по переходу, выполните следующие действия:

  1. Чтобы запустить Помощник по обновлению, выберите Tools (Инструменты) > AGP Upgrade Assistant (Помощник по обновлению AGP) или нажмите на уведомление, как показано на рисунке 1.

    В появившемся окне инструмента отображаются сведения об обновлении по умолчанию, включая текущую версию AGP проекта и последнюю версию, поддерживаемую этой версией Android Studio.

    Окно инструмента AGP Upgrade Assistant при запуске и уведомление.
    Рисунок 1. Окно инструмента AGP Upgrade Assistant, запущенного из уведомления.

  2. Ознакомьтесь с обязательными и рекомендуемыми действиями.

    На панели слева находится дерево с флажками, в котором перечислены отдельные шаги обновления. Они разделены на обязательные и рекомендуемые, а также на те, которые являются необходимыми условиями для других шагов. Чтобы посмотреть подробные сведения о каждом шаге, выберите нужный элемент в дереве.

  3. Чтобы запустить обновление, выберите нужные шаги и нажмите Выполнить выбранные шаги.

    Помощник по обновлению изменит файлы сборки проекта и попытается синхронизировать новую сборку проекта с Android Studio. Если у вас много модулей, это может занять некоторое время, поскольку может потребоваться загрузить новые версии плагинов и библиотек.

  4. Проверьте отчет о преобразовании. В этом отчете описываются выполненные шаги и указывается, было ли обновление успешным. Также в нем есть действие, позволяющее отменить изменения, внесенные помощником по обновлению, если после обновления возникли проблемы со сборкой или тестированием проекта.

  5. После успешной синхронизации проекта с Android Studio соберите проект и запустите наборы тестов, чтобы убедиться, что обновление не повлияло на функциональность.

  6. Убедившись, что проект работает правильно, зафиксируйте его новую версию в системе управления версиями.

Устранение ошибок

Если Помощник по обновлению предлагает обновление, но оно не выполняется, обычно это связано с изменениями в файлах сборки, которые приводят к сбою синхронизации. Чтобы устранить ошибку, выполните следующие действия:

  • Сначала изучите ошибку, которая привела к сбою синхронизации. Иногда причина ошибки очевидна и ее можно устранить в файлах сборки проекта.

  • Если сообщение об ошибке неясно или неочевидно, что вызывает проблему, верните проект в исходное состояние, чтобы разбить обновление на более мелкие шаги. Восстановите исходное состояние из системы управления версиями или резервных копий и убедитесь, что проект находится в исходном состоянии и синхронизирован с Android Studio.

Чтобы разобраться в проблеме, изучите два типа разбивки:

  • Перейти на другую версию AGP, которая не является последней версией. Если вы обновляли сразу несколько версий, то, чтобы найти проблему, лучше всего выполнить несколько обновлений меньшего масштаба – от версии к версии. Так вы сможете определить, на каком этапе возникает ошибка.

  • Выполняйте шаги по одному. Определив, какое обновление вызывает проблему, вы можете отключить отдельные шаги в нем. Если это возможно, попробуйте выполнять каждый шаг по одному, чтобы выяснить, какой из них вызывает ошибку. Если вы не можете найти нужный шаг, проверьте примечания к выпуску других плагинов Gradle, которые вы используете, на наличие проблем совместимости с Gradle или AGP. Иногда в новой версии исправляется использование устаревших или внутренних API.

  • Сообщить об ошибке. Иногда все подготовительные шаги и синхронизация проходят успешно, но на последнем этапе обновления возникает ошибка. В этом случае сообщите об ошибке. Даже если вы сможете устранить ошибку самостоятельно, сообщите о ней в системе отслеживания ошибок, чтобы команда разработчиков могла ее исправить.