CocoaPods Plugin — что это такое, плагин для KMM и настройка

Что такое CocoaPods Plugin?

CocoaPods Plugin (также известный как kotlin.cocoapods) — это официальный плагин JetBrains для интеграции CocoaPods с Kotlin Multiplatform Mobile. Плагин является частью Kotlin Gradle DSL и настраивается непосредственно в build.gradle.kts KMM-модуля. Он автоматизирует создание и поддержку Podfile, генерацию .xcworkspace и управление под-зависимостями, избавляя разработчика от ручной настройки Xcode-проекта.

До появления CocoaPods Plugin разработчики KMM были вынуждены вручную создавать Podfile, запускать pod install, настраивать bridge-заголовки и следить за версиями подов отдельно от Gradle-зависимостей. Это приводило к рассинхронизации версий и сложностям в CI/CD пайплайнах. Плагин решил эти проблемы, сделав управление iOS-зависимостями таким же простым, как управление Gradle-зависимостями в модулях Android.

Плагин поддерживает как публичные поды из CocoaPods Trunk, так и кастомные поды из приватных репозиториев. Работа с локальными Podspec и git-based репозиториями также поддерживается. Плагин совместим с версиями Kotlin 1.6.0 и выше, а также требует установленного CocoaPods (gem install cocoapods) на машине разработчика.

Как работает CocoaPods Plugin

CocoaPods Plugin работает на уровне Gradle task-graph, добавляя специализированные задачи для работы с CocoaPods. Основные задачи включают podInstall (установка подов), podGenXcodeWorkspace (генерация .xcworkspace) и podBuildDebugFramework (сборка Debug-версии фреймворка). Плагин анализирует секцию cocoapods в build.gradle.kts, создаёт Podfile на основе объявленных зависимостей и запускает pod install с нужными параметрами.

Архитектура плагина включает три компонента: DSL-расширение для build.gradle.kts, Podfile Generator для создания Podfile и Xcode Integration Layer для настройки .xcworkspace. DSL-расширение предоставляет блок cocoapods { } с вложенными функциями pod() для объявления зависимостей, specRepo() для указания приватных репозиториев и framework { } для настройки выходного фреймворка. Podfile Generator транслирует эти объявления в синтаксис Ruby, понятный CocoaPods.

kotlin {
    cocoapods {
        summary = "Shared module for iOS project"
        homepage = "https://itsectr.com"
        framework {
            baseName = "Shared"
            isStatic = true
            export(project(":core"))
        }
        pod("Alamofire") {
            version = "~> 5.9"
        }
        pod("Kingfisher") {
            version = "7.12"
        }
    }
}

Жизненный цикл задачи podInstall

При выполнении podInstall плагин последовательно: генерирует Podfile в корне проекта, запускает pod install через командную строку, генерирует .xcworkspace, проверяет соответствие версий подов заявленным и кэширует Podfile.lock. При повторном запуске без изменений конфигурации podInstall пропускается, если Podfile.lock не изменился. Это экономит время в CI/CD, где pod install может занимать до 2–3 минут на чистую установку.

Настройка CocoaPods Plugin в KMM-проекте

Для настройки CocoaPods Plugin необходимо выполнить несколько шагов. Установка CocoaPods на машине разработчика (gem install cocoapods) — обязательное условие. Затем в build.gradle.kts shared-модуля добавляется блок cocoapods { } с конфигурацией фреймворка и зависимостей. После настройки нужно выполнить задачу podInstall, которая создаст Podfile и установит поды. Сгенерированный .xcworkspace будет располагаться в корне проекта рядом с Podfile.

Плагин интегрируется с Xcode Build Phases. При сборке iOS-приложения Xcode запускает embedAndSignAppleFrameworkForXcode — задачу, которая копирует Kotlin/Native фреймворк в бандл приложения. CocoaPods Plugin добавляет эту build phase автоматически при генерации .xcworkspace. Если .xcworkspace был сгенерирован, его необходимо открывать вместо .xcodeproj для корректной сборки с под-зависимостями.

Примеры кода: конфигурация подов

Рассмотрим различные сценарии объявления подов в CocoaPods Plugin. Базовый случай — подключение публичного пода из CocoaPods Trunk с указанием версии. Более сложные сценарии включают использование кастомных podspec, локальных подов и подов из git-репозиториев.

kotlin {
    iosArm64()
    iosSimulatorArm64()

    cocoapods {
        framework {
            baseName = "Shared"
            isStatic = false
        }

        // Public pod from CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Custom version with operator
        pod("SnapKit") { version = "~> 5.6" }

        // Pod from private repo
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Local pod with path
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // Pod from git repo
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

Подключение подов — только часть конфигурации. Плагин также позволяет экспортировать зависимости из других Kotlin-модулей в iOS-фреймворк. Функция export(project(":core")) указывает, что все публичные API модуля :core должны быть доступны из Objective-C-заголовка сгенерированного фреймворка. Это необходимо, когда общий Kotlin-код использует классы из другого модуля, и они должны быть доступны из Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Export modules to iOS framework
        export(project(":network"))
        export(project(":domain"))

        // Static or dynamic linking
        isStatic = true
    }

    // Pod required for exported modules
    pod("Moya") { version = "15.0" }
}

Сборка и тестирование

После настройки конфигурации необходимо выполнить podInstall для генерации Podfile и установки зависимостей. Затем сгенерированный .xcworkspace открывается в Xcode, где можно собрать приложение стандартным способом. Для CI/CD необходимо убедиться, что на сборочной машине установлены CocoaPods и Ruby. Плагин поддерживает флаг --no-daemon для работы в CI-среде.

// Install pods generates Podfile + xcworkspace
./gradlew :shared:podInstall

// Build debug framework for testing
./gradlew :shared:podBuildDebugFramework

// Full iOS build from command line
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — альтернативный менеджер зависимостей от Apple, который набирает популярность и постепенно вытесняет CocoaPods в iOS-сообществе. Однако CocoaPods Plugin остаётся актуальным по нескольким причинам: SPM не поддерживает динамические фреймворки в KMM-контексте, а интеграция Kotlin/Native фреймворка через SPM требует дополнительных настроек. CocoaPods Plugin предоставляет более зрелый и документированный путь интеграции.

Сравнение CocoaPods Plugin и прямой интеграции через SPM показывает, что первый выигрывает в автоматизации, а второй — в нативной поддержке Apple. CocoaPods Plugin автоматически генерирует Podfile, управляет версиями и настраивает Xcode Build Phases. SPM требует ручного подключения Kotlin-фреймворка через Package.swift, что сложнее в поддержке для крупных KMM-проектов. JetBrains работает над поддержкой SPM для Kotlin/Native, но на 2025 год SPM-интеграция остаётся экспериментальной.

Типичные проблемы и решения

При использовании CocoaPods Plugin KMM-разработчики сталкиваются с несколькими типичными проблемами. Конфликт версий подов — наиболее частая проблема, когда два пода требуют разные версии одной зависимости. Решением является явное указание версии конфликтующей зависимости через pod("Dependency") { version = "x.x" }. Второй распространённый случай — несовместимость версий, когда под требует iOS SDK новее, чем минимальная версия KMM-проекта.

Проблемы с .xcworkspace возникают, если открывать .xcodeproj вместо .xcworkspace после настройки плагина. Плагин предупреждает об этом в логах podInstall. Другая частая ошибка — отсутствие CocoaPods на машине разработчика. Плагин проверяет наличие pod команды перед запуском podInstall и выводит понятное сообщение об ошибке. Для CI/CD необходимо установить CocoaPods: gem install cocoapods.

// Resolve version conflict
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Explicitly resolve conflict
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Check CocoaPods installation via Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods version: $result")
    }
}

Отладка podInstall

Если podInstall завершается с ошибкой, используйте флаг --info для подробного вывода: ./gradlew podInstall --info. Плагин логирует каждый шаг: генерацию Podfile, запуск pod install, парсинг Podfile.lock. Чаще всего ошибки связаны с сетевыми проблемами (недоступность CocoaPods Trunk) или неверным синтаксисом Podfile. В таких случаях попробуйте запустить pod install вручную в корне проекта для получения более детального сообщения об ошибке от CocoaPods.