Миграция проектов Kotlin Multiplatform на 1.4.0

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

Для авторов многоплатформенных проектов

Обновить Gradle

Начиная с 1.4.0, проекты Kotlin multiplatform требуют Gradle 6.0 или более поздней версии. Убедитесь, что ваши проекты используют правильную версию Gradle, и обновите её, если необходимо. Обратитесь к документации Gradle для инструкций по миграции, не связанных с Kotlin.

Упростить конфигурацию сборки

Метаданные модулей Gradle предоставляют богатые функции публикации и разрешения зависимостей, которые используются в проектах Kotlin Multiplatform. В Gradle 6.0 и выше метаданные модулей используются в разрешении зависимостей и включаются в публикации по умолчанию. Таким образом, после обновления до Gradle 6.0 вы можете удалить enableFeaturePreview("GRADLE_METADATA") из файла settings.gradle проекта.

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

Начиная с 1.4.0, вам также больше не нужно вручную объявлять зависимость от stdlib в каждом наборе исходных кодов – она теперь будет добавляться по умолчанию. Версия автоматически добавленной стандартной библиотеки будет такой же, как и версия плагина Kotlin Gradle, так как они имеют одинаковую версионирование.

Благодаря этим функциям вы можете сделать файл Gradle сборки более лаконичным и удобочитаемым:

...
android()
ios()
js()

sourceSets {
    commonMain {
        dependencies {
            implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutinesVersion")
        }
    }
}

...

Не используйте имена артефактов библиотеки kotlinx с суффиксами -common или -native, так как они больше не поддерживаются. Вместо этого используйте имя корневого артефакта библиотеки, которое в примере выше равно kotlinx-coroutines-core.

Попробуйте иерархическую структуру проекта

С поддержкой новой иерархической структуры проекта, вы можете использовать код в нескольких целевых платформах в многоплатформенном проекте. Вы можете использовать платформенно-зависимые библиотеки, такие как Foundation, UIKit, и posix в наборах исходных кодов, общих для нескольких целевых платформ. Это может помочь вам использовать больше кода нативных платформ без ограничений платформенно-специфичных зависимостей.
Включив иерархическую структуру вместе с возможностью использования платформенно-зависимых библиотек в общих наборах исходных кодов, вы можете избежать необходимости использования определённых обходных путей для получения поддержки IDE для совместного использования наборов исходных кодов между несколькими нативными целевыми платформами, например iosArm64 и iosX64:

kotlin {
    // workaround 1: select iOS target platform depending on the Xcode environment variables
    val iOSTarget: (String, KotlinNativeTarget.() -> Unit) -> KotlinNativeTarget =
        if (System.getenv("SDK_NAME")?.startsWith("iphoneos") == true)
            ::iosArm64
        else
            ::iosX64

    iOSTarget("ios") 
}

# workaround 2: make symbolic links to use one source set for two targets
ln -s iosMain iosArm64Main && ln -s iosMain iosX64Main

Вместо этого вы можете создать иерархическую структуру с сокращениями для целевых платформ, доступными для типичных многоцелевых сценариев, или вручную объявить и подключить наборы исходных кодов. Например, вы можете создать два целевых устройства iOS и общий набор исходных кодов с сокращением ios():

kotlin {
   ios() // iOS device and simulator targets; iosMain and iosTest source sets
}

Чтобы включить иерархическую структуру проекта вместе с использованием платформенно-зависимых библиотек в общих наборах исходных кодов, добавьте следующее в ваш gradle.properties:

kotlin.mpp.enableGranularSourceSetsMetadata=true
kotlin.native.enableDependencyPropagation=false

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

Для авторов библиотек

Проверка загрузки на Bintray

Плагин Bintray не поддерживает публикацию метаданных модулей Gradle, но есть несколько способов решить эту проблему:

Перейти к maven-publish вместо bintray-publish как мы сделали для kotlinx.serialization
Используйте обходной путь для плагина Bintray

При загрузке вашей библиотеки на Bintray вы увидите несколько версий для каждого артефакта (например, my-library-jvm, my-library-metadata, и т.д.). Чтобы исправить это, добавьте systemProp.org.gradle.internal.publish.checksums.insecure=true. Подробности см. в этой проблеме. Это распространённая проблема Gradle 6.0, которая не связана с MPP и Kotlin.

Следовать стандартному расположению библиотек

Структура kotlinx библиотек изменилась и теперь соответствует стандартному расположению, которое мы рекомендуем использовать: модуль библиотеки «корень» или «зонтик» теперь имеет имя без суффикса (например, kotlinx-coroutines-core вместо kotlinx-coroutines-core-native). Публикация библиотек с плагином Gradle maven-publish по умолчанию следует этому расположению.

Перейти к иерархической структуре проекта

Иерархическая структура проекта позволяет повторно использовать код в похожих целях, а также публиковать и потреблять библиотеки с детализированными API, нацеленными на похожие платформы. Мы рекомендуем переключиться на иерархическую структуру проекта в ваших библиотеках при миграции на Kotlin 1.4.0:

Библиотеки, опубликованные с иерархической структурой проекта, совместимы со всеми типами проектов, как с иерархической, так и без неё. Однако, библиотеки, опубликованные без иерархической структуры проекта, не могут использоваться в общем нативном наборе исходных кодов. Таким образом, например, пользователи с сокращениями ios() в своих файлах gradle.build не смогут использовать вашу библиотеку в своём iOS-совместимом коде.
В будущих версиях иерархическая структура проекта с использованием платформенно-зависимых библиотек в общих наборах исходных кодов станет стандартной в многоплатформенных проектах. Чем скорее вы её поддержите, тем скорее пользователи смогут мигрировать. Мы также будем очень признательны, если вы сообщите нам о найденных ошибках в наш трекер проблем.

Чтобы включить поддержку иерархической структуры проекта, добавьте следующее в ваш gradle.properties:

kotlin.mpp.enableGranularSourceSetsMetadata=true

Для авторов сборки

Проверить имена задач

Введение иерархической структуры проекта в многоплатформенные проекты привело к некоторым изменениям в именах некоторых задач Gradle:

Задача metadataJar была переименована в allMetadataJar
Есть новые задачи compile<SourceSet>KotlinMetadata для всех опубликованных промежуточных наборов исходных кодов

Эти изменения актуальны только для проектов с иерархической структурой проекта.

Для использования целевой платформы Kotlin/JS

При объявлении зависимостей от пакетов npm теперь требуется явно указать версию или диапазон версий, основанный на синтаксисе semver npm. Также поддерживается указание нескольких диапазонов версий.

Хотя мы этого не рекомендуем, вы можете использовать символ «звездочка» * вместо номера версии, если не хотите явно указывать версию или диапазон версий.

Kotlin 1.4.0 включает альфа-компилятор IR для Kotlin/JS. Для получения более подробной информации о бэкенде компилятора Kotlin/JS IR и о том, как его настроить, обратитесь к документации.

Чтобы выбрать между различными вариантами компилятора Kotlin/JS, установите ключ kotlin.js.compiler в вашем gradle.properties в legacy, ir, или both. В качестве альтернативы передайте LEGACY, IR, или BOTH в функцию js в вашем build.gradle(.kts).

kotlin {
    js(IR) { // or: LEGACY, BOTH
        // . . .
    }
    binaries.executable()
}

Изменения в `both` режиме

Выбор both в качестве опции компилятора (чтобы он компилировался как с устаревшим, так и с IR бэкендом) означает, что некоторые задачи Gradle переименованы, чтобы явно обозначить, что они затрагивают только устаревшую компиляцию. compileKotlinJs переименована в compileKotlinJsLegacy, и compileTestKotlinJs переименована в compileTestKotlinJsLegacy.

Явное включение/выключение создания исполняемых файлов

При использовании компилятора IR инструкция binaries.executable() должна быть в блоке конфигурации целевой платформы js вашего build.gradle(.kts) . Если этот параметр опущен, генерируются только внутренние файлы Kotlin-библиотеки. Эти файлы могут использоваться из других проектов, но не запускаться самостоятельно.

Для обратной совместимости, при использовании устаревшего компилятора для Kotlin/JS, включение или исключение binaries.executable() не повлияет — исполняемые файлы будут сгенерированы в любом случае. Чтобы заставить устаревший бэкенд прекратить создание исполняемых файлов без наличия binaries.executable() (например, для ускорения сборки, где исполняемые артефакты не требуются), установите kotlin.js.generate.executable.default=false в вашем gradle.properties.

Интеграция Dukat для Gradle претерпела незначительные изменения в именовании и функциональности с Kotlin 1.4.0.

Флаг kotlin.js.experimental.generateKotlinExternals был переименован в kotlin.js.generate.externals. Он управляет поведением Dukat по умолчанию для всех указанных зависимостей npm.
Функция зависимости npm теперь принимает третий параметр после имени и версии пакета: generateExternals. Это позволяет индивидуально контролировать, должен ли Dukat генерировать объявления для конкретной зависимости, и переопределяет настройку generateKotlinExternals.

Также доступен способ ручного запуска генерации Kotlin externals. Для получения дополнительной информации, пожалуйста, обратитесь к документации.

Использование артефактов, созданных с Kotlin 1.4.x в проекте Kotlin 1.3.x

Выбор между компиляторами IR и LEGACY еще не был доступен в Kotlin 1.3.xx. Из-за этого вы можете столкнуться с ошибкой Gradle Cannot choose between the following variants... , если одна из ваших зависимостей (или любая транзитивная зависимость) была создана с использованием Kotlin 1.4+, а ваш проект использует Kotlin 1.3.xx. Временное решение предоставлено здесь.

© 2010–2020 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/reference/migrating-multiplatform-project-to-14.html