Обновите проекты Kotlin для Android Gradle Plugin 9.0

Мартон Браун пишет о внедрении Gradle Plugin 9.0:

Плагин Android Gradle 9.0 уже доступен, и он включает в себя два важных изменения, которые затронут существующие проекты на Kotlin:

• Android-приложения должны начать использовать встроенную в AGP 9.0 поддержку Kotlin.
• Проекты Kotlin Multiplatform, ориентированные на Android, должны перейти на новый плагин библиотеки Android KMP.

В этом посте приведены некоторые подробности об этих изменениях и указаны ресурсы, которые понадобятся вам для обновления существующих проектов.

Вам также нужно будет обновить инструменты и плагины, которые зависят от AGP, до последних версий с поддержкой AGP 9.0. Если вы используете Android Studio, вам нужно использовать Otter 3 Feature Drop или более позднюю версию.

Примечание: Поддержка AGP 9.0 скоро появится в IntelliJ IDEA, ожидается в 1 квартале 2026 года.

Информацию о совместимости плагинов Gradle вы можете найти на этой странице, поддерживаемой сообществом.

Мы работаем над внедрением AGP 9.0 в нашу документацию, примеры и мастера. Это означает, что все они будут использовать AGP 9.0 по умолчанию и уже включат эти изменения в свои соответствующие конфигурации.

Использование встроенного Kotlin

Ранее для добавления поддержки исходных файлов Kotlin в проекты Android требовалось применять плагин Kotlin Android (org.jetbrains.kotlin.android). В AGP 9.0 поддержка Kotlin встроена и включена по умолчанию, поэтому больше не нужно отдельно применять плагин Kotlin Android для Android-приложений.

Основным шагом миграции здесь является удаление использования плагина Kotlin Android из ваших проектов. Однако если ваш проект использует kapt для обработки аннотаций или устанавливает пользовательские kotlinOptions, вам нужно будет обновить и эти конфигурации.

Ознакомьтесь с руководством по миграции в документации по Android, чтобы получить пошаговые инструкции.

В AGP 9.0 вы все еще можете временно отказаться от этих изменений, добавив android.builtInKotlin=false и android.newDsl=false в gradle.properties. Однако это больше не будет работать в AGP 10.0, который ожидается где-то в 2026 году.

Используйте новый плагин библиотеки Android KMP

В предыдущих версиях плагин Android Gradle предоставлял два различных плагина, которые можно было применить к модулю:

• Плагин библиотеки Android (com.android.library)
• Плагин для Android-приложений (com.android.application)

Любой из них можно было использовать в сочетании с плагином KMP (org.jetbrains.kotlin.multiplatform) для создания vekmnbплатформенного модуля.

В AGP 9.0 появился новый, упрощенный плагин библиотеки KMP для Android (com.android.kotlin.multiplatform.library), созданный специально для мультиплатформенных проектов. Ранее использовавшиеся плагины для библиотек и приложений Android больше не совместимы с плагином KMP в одном модуле, что означает, что вам нужно будет перенести все мультиплатформенные модули на новый плагин. Эта миграция будет отличаться для библиотечных модулей и модулей приложений. Подробнее об обоих сценариях вы можете узнать ниже.

В AGP 9.0 вы все еще можете временно отказаться от этих изменений, добавив android.enableLegacyVariantApi=true в gradle.properties. Однако это больше не будет работать в AGP 10.0, который ожидается где-то в 2026 году.

Миграция библиотечного модуля

Если у вас есть модуль, который использует плагин библиотеки Android и плагин Kotlin Multiplatform вместе, вам придется заменить плагин библиотеки Android на плагин библиотеки Android KMP. Это означает, что вам придется обновить конфигурацию сборки вашего существующего модуля, но в целом никаких изменений в структуре проекта или исходном коде не требуется.

Новый плагин библиотеки Android KMP имеет настройки по умолчанию, разработанные для Kotlin Multiplatform и оптимизированные для скорости и стабильности сборки. Некоторые прежние параметры конфигурации были удалены или перенесены в новые API.

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

Миграция модуля приложения

Во многих проектах в одном и том же модуле применяются как плагин для Android-приложений, так и плагин Kotlin Multiplatform. Такой модуль содержит общий многоплатформенный код, а также Android-приложение со всеми связанными с ним конфигурациями сборки. В прошлом это была рекомендуемая структура, и если вы создали свой проект с помощью мастера KMP, то, скорее всего, в вашем проекте есть один модуль composeApp, настроенный подобным образом.

Модули, подобные этому, также должны быть мигрированы для использования нового плагина библиотеки Android KMP в модуле, содержащем общий код, что требует нескольких шагов.

Во-первых, вам придется создать новый модуль для точки входа вашего приложения и применить в нем плагин для Android-приложений. Этот новый модуль может быть относительно небольшим и простым, содержащим конфигурацию сборки для упаковки Android-приложения и его точки входа, например классы Activity и Application (на иллюстрациях здесь они представлены MainActivity).

При использовании AGP 9.0 этому новому модулю не нужно применять плагин Kotlin, так как он может использовать встроенную поддержку Kotlin (как подробно описано выше).

Затем этот новый прикладной модуль должен зависеть от существующего мультиплатформенного модуля, чтобы иметь доступ к его содержимому. Теперь мультиплатформенный модуль может стать Android-библиотекой, что означает, что вы должны перенести его на новый плагин библиотеки Android KMP.

Чтобы перенести модуль Android-приложения на AGP 9.0, следуйте подробным шагам в руководстве по миграции.

Заключение

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

В дополнение к приведенным выше ссылкам вы можете прочитать полное описание релиза AGP 9.0, чтобы узнать больше о нововведениях.

Если у вас возникли проблемы с самим AGP 9.0, создайте новую issue в компоненте Android Studio в трекере проблем Google.

Для решения проблем, связанных с плагином Kotlin Multiplatform IDE, создайте задачу в трекере KMT.

Чтобы оставить отзыв о документации по Kotlin, создайте проблему на YouTrack или сообщите о ней в канале #multiplatform в Kotlinlang Slack.