Руководство по совместимости Kotlin Multiplatform

Переход на плагин Google для целевых платформ Android

Что изменилось?

До Kotlin 2.3.0 мы предоставляли поддержку целевой платформы Android с помощью плагинов com.android.application и com.android.library. Это было временное решение на период разработки командой Android в Google отдельного плагина, предназначенного для Kotlin Multiplatform.

Изначально мы использовали блок android, но позднее перешли на блок androidTarget, чтобы имя android можно было зарезервировать для нового плагина.

Теперь команда Android предоставляет плагин com.android.kotlin.multiplatform.library, который можно использовать с исходными блоками android.

В Kotlin 2.3.0 появляется предупреждение об устаревании, если в проектах Kotlin Multiplatform используется имя androidTarget. Если вам нужно больше времени для перехода на блок android, используйте Kotlin 2.3.10 с AGP 8.x, где это предупреждение не появляется.

Как теперь лучше поступить?

Перейдите на новый плагин com.android.kotlin.multiplatform.library. Переименуйте все вхождения блока androidTarget в android. Подробные инструкции по переходу см. в руководстве по миграции Google.

Когда изменения вступят в силу?

Ниже приведен цикл устаревания для плагина Kotlin Multiplatform Gradle:

• 1.9.0: добавить предупреждение об устаревании при использовании имени android в проектах Kotlin Multiplatform

• 2.1.0: повысить уровень этого предупреждения до ошибки

• 2.2.0: удалить DSL целевой платформы android из плагина Kotlin Multiplatform Gradle

• 2.3.0: становится доступен новый плагин Android; добавить предупреждение об устаревании при использовании имени androidTarget в проектах Kotlin Multiplatform.

• 2.3.10: отменить предупреждение об устаревании при использовании имени androidTarget в проектах Kotlin Multiplatform.

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

Что изменилось?

Встраивание биткода устарело в Xcode 14 и было удалено в Xcode 15 для всех целевых платформ Apple. В связи с этим в Kotlin устаревают параметр embedBitcode для конфигурации фреймворка, а также аргументы командной строки -Xembed-bitcode и -Xembed-bitcode-marker.

Как теперь лучше поступить?

Если вы по-прежнему используете более ранние версии Xcode, но хотите перейти на Kotlin 2.0.20 или более позднюю версию, отключите встраивание биткода в проектах Xcode.

Когда изменения вступят в силу?

Ниже приведен планируемый цикл устаревания:

• 2.0.20: компилятор Kotlin/Native больше не поддерживает встраивание биткода

• 2.1.0: DSL embedBitcode устаревает в плагине Kotlin Multiplatform Gradle с выдачей предупреждения

• 2.2.0: предупреждение повышается до ошибки

• 2.3.0: DSL embedBitcode удаляется

Наборы исходного кода Java создаются по умолчанию

Что изменилось?

Чтобы привести Kotlin Multiplatform в соответствие с предстоящими изменениями в Gradle, мы постепенно отказываемся от функции withJava(). Функция withJava() обеспечивала интеграцию с плагинами Java для Gradle, создавая необходимые наборы исходного кода Java. Начиная с Kotlin 2.1.20 эти наборы исходного кода Java создаются по умолчанию.

Как теперь лучше поступить?

Раньше для создания наборов исходного кода src/jvmMain/java и src/jvmTest/java требовалось явно использовать функцию withJava():

kotlin {
    jvm {
        withJava()
    }
}

Начиная с Kotlin 2.1.20, функцию withJava() можно удалить из скрипта сборки.

Кроме того, теперь Gradle запускает задачи компиляции Java, только если в проекте есть исходный код Java. Это приводит к выполнению диагностики проверки JVM, которая раньше не запускалась. Диагностика завершается ошибкой, если для задач KotlinJvmCompile или внутри compilerOptions явно настроена несовместимая целевая платформа JVM. Рекомендации по обеспечению совместимости целевых платформ JVM см. в разделе Проверка совместимости целевых платформ JVM связанных задач компиляции.

Если в вашем проекте используется версия Gradle выше 8.7 и он не зависит от плагинов Java для Gradle, таких как Java, Java Library или Application, либо от стороннего плагина Gradle, зависящего от плагина Java для Gradle, функцию withJava() можно удалить.

Если в проекте используется плагин Java для Gradle Application, рекомендуем перейти на новый экспериментальный DSL. Начиная с Gradle 8.7 плагин Application больше не будет работать с плагином Kotlin Multiplatform Gradle.

Если в многоплатформенном проекте вы хотите использовать плагин Kotlin Multiplatform Gradle вместе с другими плагинами Gradle для Java, см. раздел Устаревшая совместимость плагина Kotlin Multiplatform Gradle с плагинами Java.

Если вы используете плагин Gradle Java test fixtures с Kotlin 2.1.20 и версией Gradle выше 8.7, этот плагин не работает. Вместо этого перейдите на Kotlin 2.1.21, где эта проблема устранена.

Если у вас возникнут проблемы, сообщите о них в трекере задач или попросите о помощи в нашем открытом канале Slack.

Когда изменения вступят в силу?

Ниже приведен планируемый цикл устаревания:

• Gradle >8.6: добавить предупреждение об устаревании для любой предыдущей версии Kotlin в многоплатформенных проектах, использующих функцию withJava().

• Gradle 9.0: повысить уровень этого предупреждения до ошибки.

• 2.1.20: добавить предупреждение об устаревании при использовании функции withJava() с любой версией Gradle.

Объявление нескольких схожих целевых платформ

Что изменилось?

Мы не рекомендуем объявлять несколько схожих целевых платформ в одном проекте Gradle. Например:

kotlin {
    jvm("jvmKtor")
    jvm("jvmOkHttp") // Not recommended and produces a deprecation warning
}

Один из распространенных вариантов — объединить два связанных фрагмента кода. Например, в проекте Gradle :shared может потребоваться использовать jvm("jvmKtor") и jvm("jvmOkHttp") для реализации сетевого взаимодействия с помощью библиотек Ktor или OkHttp:

// shared/build.gradle.kts:
kotlin {
    jvm("jvmKtor") {
        attributes.attribute(/* ... */)
    }
    jvm("jvmOkHttp") {
        attributes.attribute(/* ... */)
    }

    sourceSets {
        val commonMain by getting
        val commonJvmMain by sourceSets.creating {
            dependsOn(commonMain)
            dependencies {
                // Shared dependencies
            }
        }
        val jvmKtorMain by getting {
            dependsOn(commonJvmMain)
            dependencies {
                // Ktor dependencies
            }
        }
        val jvmOkHttpMain by getting {
            dependsOn(commonJvmMain)
            dependencies {
                // OkHttp dependencies
            }
        }
    }
}

Такая реализация требует нетривиальной настройки:

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

• Необходимо вручную настроить набор исходного кода commonJvmMain.

• Для настройки используются несколько низкоуровневых абстракций и API Gradle и плагина Kotlin Gradle.

Как теперь лучше поступить?

Настройка сложна, потому что реализации на основе Ktor и OkHttp находятся в одном проекте Gradle. Во многих случаях эти части можно вынести в отдельные проекты Gradle. Ниже приведен общий план такого рефакторинга:

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

   // shared/build.gradle.kts:
   kotlin {
       jvm()
   
       sourceSets {
           jvmMain {
               // Copy the configuration of jvmCommonMain here
           }
       }
   }
   

2. Добавьте два новых проекта Gradle, обычно вызвав include в файле settings.gradle.kts. Например:

   include(":okhttp-impl")
   include(":ktor-impl")
   

3. Настройте каждый новый проект Gradle:

   • Скорее всего, вам не потребуется применять плагин kotlin("multiplatform"), поскольку эти проекты компилируются только для одной целевой платформы. В этом примере можно применить kotlin("jvm").

   • Перенесите содержимое исходных наборов, относящихся к целевым платформам, в соответствующие проекты, например из jvmKtorMain в ktor-impl/src.

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

   • Добавьте зависимость нового проекта Gradle от исходного проекта.

   // ktor-impl/build.gradle.kts:
   plugins {
       kotlin("jvm")
   }
   
   dependencies {
       project(":shared") // Add dependency on the original project
       // Copy dependencies of jvmKtorMain here
   }
   
   kotlin {
       compilerOptions {
           // Copy compiler options of jvmKtorMain here
       }
   }
   

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

Когда изменения вступят в силу?

Ниже приведен планируемый цикл устаревания:

• 1.9.20: добавить предупреждение об устаревании при использовании нескольких схожих целевых платформ в проектах Kotlin Multiplatform

• 2.1.0: сообщать об ошибке в таких случаях, за исключением целевых платформ Kotlin/JS; подробнее об этом исключении см. запрос в YouTrack

Устаревшая поддержка многоплатформенных библиотек, опубликованных в устаревшем режиме

Что изменилось?

Ранее мы объявили устаревшим устаревший режим в проектах Kotlin Multiplatform, который предотвращает публикацию «устаревших» бинарных файлов, и рекомендовали перенести проекты на иерархическую структуру.

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

The dependency group:artifact:1.0 was published in the legacy mode. Support for such dependencies will be removed in the future

Как теперь лучше поступить?

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

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

Если вы автор библиотеки, обновите плагин Kotlin Gradle до последней версии и убедитесь, что вы исправили устаревшие свойства Gradle.

Команда Kotlin стремится помочь экосистеме выполнить переход, поэтому, если у вас возникнут проблемы, создайте запрос в YouTrack.

Когда изменения вступят в силу?

Ниже приведен планируемый цикл устаревания:

• 1.9.0: добавить предупреждение об устаревании для зависимостей от устаревших библиотек

• 2.0.0: повысить уровень предупреждения для зависимостей от устаревших библиотек до ошибки

• >2.0.0: удалить поддержку зависимостей от устаревших библиотек; использование таких зависимостей может привести к сбоям сборки

Устаревшие свойства Gradle для поддержки иерархической структуры

Что изменилось?

В ходе развития Kotlin поддержка иерархической структуры постепенно добавлялась в многоплатформенные проекты. Она позволяет создавать промежуточные наборы исходного кода между общим набором исходного кода commonMain и набором для конкретной платформы, например jvmMain.

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

Начиная с Kotlin 1.6.20 поддержка иерархической структуры проекта включена по умолчанию. Однако эти свойства сохранили, чтобы можно было отключить ее при возникновении блокирующих проблем. После обработки всех отзывов мы начинаем полностью отказываться от этих свойств.

Теперь следующие свойства объявлены устаревшими:

• kotlin.internal.mpp.hierarchicalStructureByDefault

• kotlin.mpp.enableCompatibilityMetadataVariant

• kotlin.mpp.hierarchicalStructureSupport

• kotlin.mpp.enableGranularSourceSetsMetadata

• kotlin.native.enableDependencyPropagation

Как теперь лучше поступить?

• Удалите эти свойства из файлов gradle.properties и local.properties.

• Не задавайте их программно в скриптах сборки Gradle или плагинах Gradle.

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

Поскольку с Kotlin 1.6.20 поведение цепочки инструментов Kotlin по умолчанию не зависит от таких свойств, мы не ожидаем серьезных последствий. Большинство изменений будет заметно сразу после повторной сборки проекта.

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

Когда изменения вступят в силу?

Ниже приведен планируемый цикл устаревания:

• 1.8.20: выводить предупреждение при использовании устаревших свойств Gradle

• 1.9.20: повысить уровень этого предупреждения до ошибки

• 2.0.0: удалить устаревшие свойства; плагин Kotlin Gradle игнорирует их использование

Если маловероятные проблемы все же возникнут после удаления этих свойств, создайте запрос в YouTrack.

Устаревший API предустановок целевых платформ

Что изменилось?

На самых ранних этапах разработки в Kotlin Multiplatform появился API для работы с так называемыми предустановками целевых платформ. Каждая предустановка по сути представляла собой фабрику целевых платформ Kotlin Multiplatform. Этот API оказался во многом избыточным, поскольку функции DSL, такие как jvm() или iosSimulatorArm64(), решают те же задачи, но значительно проще и лаконичнее.

Чтобы уменьшить путаницу и предоставить более ясные рекомендации, все API, связанные с предустановками, теперь объявлены устаревшими в публичном API плагина Kotlin Gradle. К ним относятся:

• Свойство presets в org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension

• Интерфейс org.jetbrains.kotlin.gradle.plugin.KotlinTargetPreset и все его наследники

• Перегрузки fromPreset

Как теперь лучше поступить?

Вместо них используйте соответствующие целевые платформы Kotlin, например:

kotlin {
    targets {
        fromPreset(presets.iosArm64, 'ios')
    }
}

kotlin {
    iosArm64()
}

Когда изменения вступят в силу?

Ниже приведен планируемый цикл устаревания:

• 1.9.20: выводить предупреждение при любом использовании API, связанного с предустановками

• 2.0.0: повысить уровень этого предупреждения до ошибки

• 2.2.0: удалить API, связанный с предустановками, из публичного API плагина Kotlin Gradle; исходный код, в котором он по-прежнему используется, завершит компиляцию с ошибками «unresolved reference», а бинарные файлы (например, плагины Gradle) могут завершиться ошибками связывания, если их не перекомпилировать с последними версиями плагина Kotlin Gradle

Устаревшие сокращения целевых платформ Apple

Что изменилось?

Мы объявляем устаревшими сокращения целевых платформ ios(), watchos() и tvos() в DSL Kotlin Multiplatform. Они были предназначены для частичного создания иерархии наборов исходного кода для целевых платформ Apple. Однако их оказалось сложно расширять, и иногда они вызывали путаницу.

Например, сокращение ios() создавало целевые платформы iosArm64 и iosX64, но не включало целевую платформу iosSimulatorArm64, необходимую для работы на компьютерах с чипами Apple M. Однако это сокращение было сложно изменить, не вызвав проблем в существующих проектах пользователей.

Как теперь лучше поступить?

Теперь плагин Kotlin Gradle предоставляет встроенный шаблон иерархии. Начиная с Kotlin 1.9.20 он включен по умолчанию и содержит предопределенные промежуточные наборы исходного кода для распространенных случаев использования.

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

Например, если в проекте есть целевые платформы iosArm64 и iosSimulatorArm64, плагин автоматически создаст промежуточные наборы исходного кода iosMain и iosTest. Если в проекте есть целевые платформы iosArm64 и macosArm64, будут созданы наборы исходного кода appleMain и appleTest.

Подробнее см. в разделе Иерархическая структура проекта

Когда изменения вступят в силу?

Ниже приведен планируемый цикл устаревания:

• 1.9.20: выводить предупреждение при использовании сокращений целевых платформ ios(), watchos() и tvos(); вместо них по умолчанию включается шаблон иерархии

• 2.1.0: выводить ошибку при использовании сокращений целевых платформ

• 2.2.0: удалить DSL сокращений целевых платформ из плагина Kotlin Multiplatform Gradle

Неверная версия фреймворка iOS после обновления Kotlin

В чем проблема?

При использовании прямой интеграции изменения в коде Kotlin могут не отображаться в приложении iOS в Xcode. Прямая интеграция настраивается с помощью задачи embedAndSignAppleFrameworkForXcode, которая связывает фреймворк iOS из многоплатформенного проекта с приложением iOS в Xcode.

Это может произойти, если в многоплатформенном проекте вы обновите Kotlin с версии 1.9.2x до 2.0.0 (или вернетесь с 2.0.0 на 1.9.2x), затем внесете изменения в файлы Kotlin и попробуете собрать приложение: Xcode может ошибочно использовать предыдущую версию фреймворка iOS. Поэтому изменения не будут видны в приложении iOS в Xcode.

Как обойти эту проблему?

1. В Xcode очистите каталоги сборки с помощью команды Продукт | Очистить папку сборки.

2. В терминале выполните следующую команду:

   ./gradlew clean
   

3. Соберите приложение еще раз, чтобы убедиться, что используется новая версия фреймворка iOS.

Когда проблема будет устранена?

Мы планируем устранить эту проблему в Kotlin 2.0.10. Проверить, доступны ли предварительные версии Kotlin 2.0.10, можно в разделе Участие в программе раннего доступа Kotlin.

Подробнее см. в соответствующем запросе в YouTrack.