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

Новый подход к автоматическому генерированию целей

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

Автоматически генерируемые Gradle-доступы к целям больше недоступны внутри блока kotlin.targets. Используйте метод findByName("targetName") вместо этого.

Обратите внимание, что такие доступ к целям по-прежнему доступны в случае kotlin.targets, например, kotlin.targets.linuxX64.

Какой сейчас лучший подход?

kotlin {
    targets {
        configure(['windows',
            'linux']) {
        }
    }
}

kotlin {
    targets {
        configure([findByName('windows'),
            findByName('linux')]) {
        }
    }
}

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

В Kotlin 1.7.20 при использовании доступа к целям в блоке kotlin.targets возникает ошибка.

Дополнительную информацию можно найти в соответствующем вопросе в YouTrack.

Изменения в задачах компиляции Gradle для входных и выходных данных

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

Задачи компиляции Kotlin больше не наследуют задачу Gradle AbstractCompile, имеющую входные данные sourceCompatibility и targetCompatibility, что делает их недоступными в скриптах пользователей Kotlin.

Другие прерывающие изменения в задачах компиляции:

Какой сейчас лучший подход?

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

В Kotlin 1.7.20 входные данные недоступны, вывод заменен, а свойство classpath устарело.

Дополнительную информацию можно найти в соответствующем вопросе в YouTrack.

Новые имена конфигураций зависимостей от компиляции

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

Конфигурации компиляции, созданные плагином Kotlin Multiplatform Gradle, получили новые имена.

Целевая задача в проекте Kotlin Multiplatform имеет две конфигурации компиляции по умолчанию, main и test. Каждая из этих конфигураций имеет свой собственный исходный набор, например, jvmMain и jvmTest. Раньше имена конфигураций для задачи компиляции тестов и её исходного набора были одинаковыми, что могло привести к конфликту имён и проблемам при включении конфигурации с платформенно-специфическими атрибутами в другую конфигурацию.

Теперь конфигурации компиляции имеют дополнительный суффикс Compilation, а проекты и плагины, использующие старые жёстко заданные имена конфигураций, больше не компилируются.

Имена конфигураций зависимостей от соответствующего исходного набора остаются неизменными.

Какой сейчас лучший подход?

jvm<Scope>

jvmCompilation<Scope>

dependencies {
    add("jvmImplementation",
        "foo.bar.baz:1.2.3")
}

dependencies {
    add("jvmCompilationImplementation",
        "foo.bar.baz:1.2.3")
}

jvmMain<Scope>

jvmTest<Scope>

jvmTestCompilation<Scope>

jvmTest<Scope>

Доступные области — Api, Implementation, CompileOnly, и RuntimeOnly.

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

В Kotlin 1.8.0 при использовании старых имён конфигурации в строках с жёстким кодом возникает ошибка.

Дополнительную информацию можно найти в соответствующем вопросе в YouTrack.

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

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

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

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

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

Следующие свойства теперь устарели и будут удалены в Kotlin 1.9.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 toolchain не включает такие свойства с версии 1.6.20, мы не ожидаем серьёзного влияния от их удаления. Большинство возможных последствий станут видны сразу после перестройки проекта.

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

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

В 1.8.20 плагин Kotlin Gradle выводит предупреждение, если сборка устанавливает эти свойства. Начиная с Kotlin 1.9.0, свойства будут молча игнорироваться.

В маловероятном случае, если после удаления этих свойств у вас возникнут проблемы, создайте запрос на 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: введение предупреждения об устаревании для зависимостей от устаревших библиотек

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

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

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

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

Доступ к KotlinCompilation.source устарел. Такой код генерирует предупреждение об устаревании:

kotlin {
    jvm()
    js()
    ios()
    
    sourceSets {
        val commonMain by getting 
        val myCustomIntermediateSourceSet by creating {
            dependsOn(commonMain)
        }
        
        targets["jvm"].compilations["main"].source(myCustomIntermediateSourceSet)
    }
}

Какой сейчас лучший подход?

Для замены KotlinCompilation.source(someSourceSet), добавьте отношение dependsOn от стандартного набора исходных файлов KotlinCompilation к someSourceSet. Рекомендуется обращаться к исходному коду напрямую, используя by getting, что короче и читабельнее. Однако вы также можете использовать KotlinCompilation.defaultSourceSet.dependsOn(someSourceSet), которое применимо во всех случаях.

Вы можете изменить приведенный выше код одним из следующих способов:

kotlin {
    jvm()
    js()
    ios()

    sourceSets {
        val commonMain by getting
        val myCustomIntermediateSourceSet by creating {
            dependsOn(commonMain)
        }

        // Option #1. Shorter and more readable, use it when possible:
       val jvmMain by getting { // Usually, the name of the default source set 
                                // is a simple concatenation of the target name and the compilation name
            dependsOn(myCustomIntermediateSourceSet)
        }
        
        // Option #2. Generic solution, use it if your build script requires a more advanced approach:
        targets["jvm"].compilations["main"].defaultSourceSet.dependsOn(myCustomIntermediateSourceSet)
    }
}

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

В 1.9.0 использование KotlinComplation.source генерирует предупреждение об устаревании. Этот API будет удален в Kotlin 1.9.20 и более поздних версиях, что приведет к ошибкам «неразрешенная ссылка» в вызовах KotlinCompilation.source.

Миграция с плагином Gradle kotlin-js на плагин Gradle kotlin-multiplatform

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

Начиная с Kotlin 1.9.0, плагин Gradle kotlin-js устарел. В основном, он дублировал функциональность плагина kotlin-multiplatform с целевым параметром js() и использовал ту же реализацию под капотом. Такое дублирование создавало путаницу и увеличивало нагрузку на команду Kotlin по техническому обслуживанию. Мы рекомендуем мигрировать на плагин Gradle kotlin-multiplatform с целевым параметром js() вместо него.

Какой сейчас лучший подход?

1. Удалите плагин Gradle kotlin-js из своего проекта и примените kotlin-multiplatform в файле settings.gradle.kts, если вы используете блок pluginManagement:

   // settings.gradle.kts
   pluginManagement {
       plugins {
           // Remove the following line:
           kotlin("js") version "1.9.0"
       }
   
       repositories {
           // ...
       }
   }
   

   // settings.gradle.kts
   pluginManagement {
       plugins {
           // Add the following line instead:
           kotlin("multiplatform") version "1.9.0"
       }
   
       repositories {
           // ...
       }
   }
   

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

2. Переместите файлы исходного кода из папок main и test в папки jsMain и jsTest в той же директории.

3. Отредактируйте объявления зависимостей:

   • Рекомендуется использовать блок sourceSets и настраивать зависимости соответствующих наборов исходных файлов, jsMain для зависимостей производства и jsTest для зависимостей тестирования. Подробности см. в разделе Добавление зависимостей.

   • Однако, если вы хотите объявить свои зависимости в блоке верхнего уровня, измените объявления с api("group:artifact:1.0") на add("jsMainApi", "group:artifact:1.0") и так далее.

   Вы можете изменить код в файле build.gradle.kts одним из следующих способов:

   // build.gradle.kts
   plugins {
       kotlin("js") version "1.9.0"
   }
   
   dependencies {
       testImplementation(kotlin("test"))
       implementation("org.jetbrains.kotlinx:kotlinx-html:0.8.0")
   }
   
   kotlin {
       js {
           // ...
       }
   }
   

   // build.gradle.kts
   plugins {
       kotlin("multiplatform") version "1.9.0"
   }
   
   kotlin {
       js {
           // ...
       }
   
       // Option #1. Declare dependencies in the `sourceSets` block:
       sourceSets {
           val jsMain by getting {
               dependencies {
                   // No need for the `js` prefix here, you can just copy and paste it from the top-level block
                   implementation("org.jetbrains.kotlinx:kotlinx-html:0.8.0")
               }
           }
       }
   }
   
   dependencies {
      // Option #2. Add the `js` prefix to the dependency declaration:
      add("jsTestImplementation", kotlin("test"))
   }
   

4. DSL, предоставляемый плагином Kotlin Gradle внутри блока kotlin, в большинстве случаев остается неизменным. Однако, если вы ссылались на низкоуровневые сущности Gradle, такие как задачи и конфигурации, по именам, вам теперь необходимо внести в них изменения, обычно добавив префикс js. Например, задачу browserTest можно найти под именем jsBrowserTest.

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

В 1.9.0 использование плагина Gradle kotlin-js вызывает предупреждение об устаревании.

Переименование целевого параметра android на androidTarget

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

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

Чтобы открыть путь для нового решения от Google, мы переименовали блок android на androidTarget в текущем DSL Kotlin в 1.9.0. Это временное изменение, необходимое для освобождения краткого имени android для предстоящего DSL от Google.

Какой сейчас лучший подход?

Переименуйте все вхождения блока android на androidTarget. Когда новый плагин для поддержки целевого параметра Android станет доступен, перейдите к DSL от Google. Он станет предпочтительным вариантом для работы с Android в проектах Kotlin Multiplatform.

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

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