Выбор конфигурации проекта Kotlin Multiplatform
При добавлении Kotlin Multiplatform в существующий проект или создании нового есть разные способы организовать код. Обычно создают один или несколько общих модулей Kotlin Multiplatform и используют их в приложениях для Android и iOS.
Чтобы выбрать оптимальный подход для своего случая, ответьте на следующие вопросы:
Как подключить к приложению для iOS фреймворк, созданный модулем Kotlin Multiplatform? Интегрировать его напрямую, через CocoaPods или с помощью Swift Package Manager (SwiftPM)?
У вас один или несколько общих модулей Kotlin Multiplatform? Какой модуль должен объединять несколько общих модулей?
Весь код хранится в монорепозитории или в разных репозиториях?
Модуль Kotlin Multiplatform подключается как локальная или удалённая зависимость?
Ответы на эти вопросы помогут выбрать оптимальную конфигурацию проекта.
Подключение модуля Kotlin Multiplatform к приложению для iOS
Чтобы использовать общий модуль Kotlin Multiplatform в приложении для iOS, сначала необходимо создать на его основе фреймворк для iOS. Затем нужно добавить его в качестве зависимости в проект для iOS.
В целом есть два варианта, которые реализуются по-разному:
Локальная зависимость. Сборка Kotlin напрямую взаимодействует со сборкой iOS.
Удалённая зависимость. Сборка Kotlin создаёт фреймворк для iOS, который затем подключается к проекту для iOS с помощью менеджера пакетов.
Обзор всех доступных вариантов интеграции с iOS см. в разделе Способы интеграции с iOS.
Конфигурации модулей
В проектах Kotlin Multiplatform можно использовать один из двух вариантов конфигурации модулей: один модуль или несколько общих модулей.
Один общий модуль
В самой простой конфигурации проекта есть только один общий модуль Kotlin Multiplatform:
Приложение для Android может зависеть от общего модуля Kotlin Multiplatform, как от обычного модуля Kotlin. Однако iOS не может использовать Kotlin напрямую, поэтому приложение для iOS должно зависеть от фреймворка для iOS, созданного модулем Kotlin Multiplatform.
Преимущества |
Недостатки |
|---|---|
|
|
Несколько общих модулей
По мере роста общего модуля рекомендуется разделить его на модули функций. Это помогает избежать проблем с масштабированием, связанных с наличием только одного модуля.
Приложение для Android может напрямую зависеть от всех модулей функций или, если необходимо, только от некоторых из них.
Приложение для iOS может зависеть от одного фреймворка, созданного модулем Kotlin Multiplatform. Если вы используете несколько модулей, необходимо добавить дополнительный модуль, зависящий от всех используемых модулей. Он называется объединяющим модулем. Затем нужно настроить фреймворк, содержащий все модули, — объединяющий фреймворк.
Преимущества |
Недостатки |
|---|---|
|
|
Чтобы настроить объединяющий модуль, добавьте отдельный модуль, зависящий от всех модулей функций, и создайте на его основе фреймворк:
Для единообразия приложение для Android может зависеть от объединяющего модуля или от отдельных модулей функций. Объединяющий модуль часто содержит полезные вспомогательные функции и код для настройки внедрения зависимостей.
В объединяющий фреймворк можно экспортировать только некоторые модули. Обычно это делают, когда артефакт фреймворка используется как удалённая зависимость. Основная причина — уменьшить размер итогового артефакта, исключив автоматически сгенерированный код.
Известное ограничение подхода с объединяющим фреймворком заключается в том, что приложение для iOS не может использовать только некоторые модули функций: оно автоматически использует их все. Чтобы предложить возможные улучшения этой функциональности, опишите свой случай в KT-42247 и KT-42250.
Зачем нужен объединяющий фреймворк?
Хотя в приложение для iOS можно включить несколько фреймворков, созданных на основе разных общих модулей Kotlin Multiplatform, мы не рекомендуем такой подход. При компиляции модуля Kotlin Multiplatform во фреймворк итоговый фреймворк включает все его зависимости. Если две или более модулей используют одну и ту же зависимость и представлены в iOS как отдельные фреймворки, компилятор Kotlin/Native дублирует эти зависимости.
Это дублирование вызывает ряд проблем. Во-первых, оно неоправданно увеличивает размер приложения для iOS. Во-вторых, структура кода зависимости становится несовместимой со структурой кода её дубликата. Это мешает интегрировать в приложение для iOS два модуля с одинаковыми зависимостями. Например, состояние, переданное разными модулями через одну и ту же зависимость, не будет общим. Это может привести к неожиданному поведению и ошибкам. Подробнее о конкретных ограничениях см. в документации TouchLab.
Kotlin не создаёт общие фреймворки для зависимостей, иначе возникло бы дублирование. Кроме того, любой добавляемый в приложение бинарный файл Kotlin должен быть как можно меньше. Включать всю среду выполнения Kotlin и весь код всех зависимостей нерационально. Компилятор Kotlin умеет сокращать бинарный файл, оставляя только то, что нужно для конкретной сборки. Однако он не знает, что может понадобиться для других сборок, поэтому совместное использование зависимостей нецелесообразно. Мы изучаем различные способы уменьшить влияние этой проблемы.
Решение этой проблемы — использовать объединяющий фреймворк. Он предотвращает увеличение размера приложения для iOS из-за дублирующихся зависимостей, помогает оптимизировать итоговый артефакт и устраняет проблемы, вызванные несовместимостью зависимостей.
Конфигурации репозиториев
В новых и существующих проектах Kotlin Multiplatform можно использовать несколько вариантов конфигурации репозиториев: один репозиторий или сочетание нескольких репозиториев.
Монорепозиторий: всё в одном репозитории
Распространённая конфигурация репозитория называется конфигурацией монорепозитория. Она используется в примерах и учебных материалах Kotlin Multiplatform. В этом случае репозиторий содержит приложения для Android и iOS, а также общий модуль или несколько модулей, включая объединяющий модуль:
Обычно приложение для iOS использует общий модуль Kotlin Multiplatform как обычный фреймворк, подключённый напрямую или через CocoaPods. Подробнее и ссылки на учебные материалы см. в разделе Подключение модуля Kotlin Multiplatform к приложению для iOS.
Если репозиторий находится под контролем версий, приложения и общий модуль имеют одну и ту же версию.
Преимущества |
Недостатки |
|---|---|
|
|
Если существующие приложения для Android и iOS уже хранятся в разных репозиториях, можно добавить часть Kotlin Multiplatform в репозиторий Android или в отдельный репозиторий вместо их объединения.
Два репозитория: Android + общий код | iOS
Другой вариант конфигурации проекта — использовать два репозитория. В этом случае репозиторий Kotlin Multiplatform содержит приложение для Android и общий модуль, включая объединяющий модуль, а проект Xcode содержит приложение для iOS:
Версии приложений для Android и iOS могут обновляться независимо друг от друга, а версия общего модуля обновляется вместе с версией приложения для Android.
Три репозитория: Android | iOS | общий код
Ещё один вариант — хранить модули Kotlin Multiplatform в отдельном репозитории. В этом случае приложения для Android и iOS хранятся в разных репозиториях, а общий код проекта может включать несколько модулей функций и объединяющий модуль для iOS:
Для каждого проекта можно независимо управлять версиями. Модули Kotlin Multiplatform также необходимо версионировать и публиковать для платформ Android или JVM. Модули функций можно публиковать по отдельности либо опубликовать только объединяющий модуль и сделать приложение для Android зависимым от него.
Отдельная публикация артефактов Android может усложнить работу разработчиков Android по сравнению со сценариями, в которых модули Kotlin Multiplatform являются частью проекта Android.
Когда команды Android и iOS используют артефакты одной версии, их версии синхронизированы. С точки зрения команды это позволяет избежать впечатления, будто общий код Kotlin Multiplatform «принадлежит» разработчикам Android. В крупных проектах, где уже публикуются внутренние пакеты Kotlin и Swift с версиями для разработки функций, публикация общих артефактов Kotlin становится частью существующего рабочего процесса.
Много репозиториев: Android | iOS | несколько библиотек
Если функциональность должна быть общей для нескольких приложений на разных платформах, можно хранить код Kotlin Multiplatform в нескольких репозиториях. Например, библиотеку ведения журналов, общую для всего продукта, можно хранить в отдельном репозитории с собственным управлением версиями.
В этом случае используется несколько репозиториев библиотек Kotlin Multiplatform. Если несколько приложений для iOS используют разные наборы «проектов библиотек», для каждого приложения можно создать дополнительный репозиторий с объединяющим модулем, зависящим от нужных проектов библиотек:
В этом случае каждую библиотеку также необходимо версионировать и публиковать для платформ Android или JVM. Для приложений и каждой библиотеки можно независимо управлять версиями.
Рабочий процесс совместного использования кода
Приложение для iOS может использовать фреймворк, созданный на основе общих модулей Kotlin Multiplatform, как локальную или удалённую зависимость. Чтобы использовать локальную зависимость, укажите локальный путь к фреймворку в сборке iOS. В этом случае публиковать фреймворк не нужно. Кроме того, можно опубликовать артефакт с фреймворком и подключить его к приложению для iOS как удалённую зависимость — как любую другую стороннюю зависимость.
Локальное распространение исходного кода
При локальном распространении приложение для iOS использует фреймворк модуля Kotlin Multiplatform без необходимости его публикации. Приложение для iOS может интегрировать фреймворк напрямую или через CocoaPods.
Этот рабочий процесс обычно используется, когда участники команд Android и iOS хотят редактировать общий код Kotlin Multiplatform. Разработчикам iOS необходимо установить IntelliJ IDEA или Android Studio и иметь базовые знания Kotlin и Gradle.
При локальном распространении сборка приложения для iOS запускает создание фреймворка для iOS. Это позволяет разработчикам iOS сразу видеть изменения в коде Kotlin Multiplatform:
Этот сценарий обычно используется в двух случаях. Во-первых, он может быть рабочим процессом по умолчанию в конфигурациях проектов с монорепозиторием, когда публиковать артефакты не нужно. Во-вторых, его можно использовать для локальной разработки в дополнение к удалённому рабочему процессу. Подробнее см. в разделе Настройка локальной зависимости для локальной разработки.
Этот рабочий процесс наиболее эффективен, когда все участники команды готовы редактировать код всего проекта. После внесения изменений в общие части он охватывает и Android, и iOS. В идеале у каждого участника команды должны быть установлены IntelliJ IDEA/Android Studio и Xcode, чтобы после изменения общего кода можно было открывать и запускать приложения для Android и iOS.
Преимущества |
Недостатки |
|---|---|
|
|
Удалённое распространение артефактов
При удалённом распространении артефакт фреймворка публикуется с помощью Swift Package Manager или как CocoaPod, а затем используется приложением для iOS. Приложение для Android может использовать бинарную зависимость локально или удалённо.
Удалённое распространение часто используют, чтобы постепенно внедрить эту технологию в существующие проекты. Оно не приводит к существенным изменениям рабочего процесса и процессов сборки для разработчиков iOS. Команды, работающие с двумя или более репозиториями, обычно используют удалённое распространение для хранения кода проекта.
Для начала можно воспользоваться KMMBridge — набором инструментов сборки, который значительно упрощает рабочий процесс удалённого распространения. Кроме того, можно самостоятельно настроить аналогичный процесс:
Преимущества |
Недостатки |
|---|---|
Участникам команды iOS, не работающим с общим кодом, не нужно писать код на Kotlin или учиться пользоваться такими инструментами, как IntelliJ IDEA/Android Studio и Gradle. Это значительно упрощает начало работы с технологией. |
|
Настройка локальной зависимости для локальной разработки
Многие команды при внедрении Kotlin Multiplatform выбирают рабочий процесс с удалённым распространением, чтобы сохранить привычный процесс разработки для специалистов iOS. Однако при таком подходе им трудно изменять код Kotlin Multiplatform. Мы рекомендуем дополнительно настроить рабочий процесс «локальной разработки» с локальной зависимостью от фреймворка, созданного модулем Kotlin Multiplatform.
При добавлении новой функциональности разработчики переключаются на использование модуля Kotlin Multiplatform как локальной зависимости. Это позволяет изменять общий код Kotlin, сразу проверять его поведение на iOS и отлаживать код Kotlin. Когда функциональность готова, можно вернуться к удалённой зависимости и соответствующим образом опубликовать изменения. Сначала публикуются изменения общих модулей, и только после этого вносятся изменения в приложения.
Для рабочего процесса с удалённым распространением используйте Swift Package Manager. Для локального распространения интегрируйте фреймворк напрямую.
Если вы используете CocoaPods, его также можно использовать для локального распространения. Переключаться между вариантами можно, изменяя переменную среды, как описано в документации TouchLab.
© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/multiplatform/multiplatform-project-configuration.html
