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-репозиторіями також підтримується. Плагін сумісний із версіями 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 для створення Podfile та Шар інтеграції Xcode для налаштування .xcworkspace. DSL-розширення надає блок cocoapods { } із вкладеними функціями pod() для оголошення залежностей, specRepo() для вказання приватних репозиторіїв і framework { } для налаштування вихідного фреймворку. Генератор Podfile транслює ці оголошення в синтаксис 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 спільного модуля додається блок 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
        }

        // Публічний под із CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Кастомна версія з оператором
        pod("SnapKit") { version = "~> 5.6" }

        // Под із приватного репозиторію
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Локальний под із шляхом
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // Под із git-репозиторію
        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"
        // Експортувати модулі у фреймворк iOS
        export(project(":network"))
        export(project(":domain"))

        // Статичне або динамічне компонування
        isStatic = true
    }

    // Под, необхідний для експортованих модулів
    pod("Moya") { version = "15.0" }
}

Збірка та тестування

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

// Встановлення подів генерує Podfile + xcworkspace
./gradlew :shared:podInstall

// Зібрати debug фреймворк для тестування
./gradlew :shared:podBuildDebugFramework

// Повна збірка iOS з командного рядка
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.

// Вирішити конфлікт версій
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Явно вирішити конфлікт
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Перевірити встановлення CocoaPods через Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Версія CocoaPods: $result")
    }
}

Налагодження podInstall

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