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-headers и да следят версиите на подове отделно от Gradle зависимостите. Това водеше до десинхронизация на версии и трудности в CI/CD пайплайните. Плъгинът реши тези проблеми, правейки управлението на iOS зависимости толкова просто, колкото управлението на Gradle зависимости в Android модули.

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

Как работи CocoaPods Plugin

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

Архитектурата на плъгина включва три компонента: DSL разширение за build.gradle.kts, Podfile генератор за създаване на Podfile и Xcode интеграционен слой за конфигурация на .xcworkspace. DSL разширението предоставя блок cocoapods { } с вложени функции pod() за деклариране на зависимости, specRepo() за посочване на частни хранилища и framework { } за конфигурация на изходния 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 на shared модула се добавя блок cocoapods { } с конфигурация на framework и зависимости. След конфигурацията трябва да се изпълни задачата podInstall, която ще създаде Podfile и ще инсталира подовете. Генерираният .xcworkspace ще се намира в корена на проекта до Podfile.

Плъгинът се интегрира с Xcode Build Phases. При изграждане на iOS приложението, Xcode стартира embedAndSignAppleFrameworkForXcode — задача, която копира Kotlin/Native framework в пакета на приложението. 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 framework. Функцията export(project(":core")) указва, че всички публични API на модула :core трябва да бъдат достъпни от Objective-C хедъра на генерирания framework. Това е необходимо, когато общият Kotlin код използва класове от друг модул и те трябва да бъдат достъпни от Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Експортиране на модули в iOS framework
        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 framework за тестване
./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 не поддържа динамични frameworks в KMM контекст, а интеграцията на Kotlin/Native framework чрез SPM изисква допълнителна конфигурация. CocoaPods Plugin предоставя по-зрял и документиран път за интеграция.

Сравнение на CocoaPods Plugin и директната интеграция чрез SPM показва, че първият печели в автоматизацията, а вторият — в нативната поддръжка на Apple. CocoaPods Plugin автоматично генерира Podfile, управлява версиите и конфигурира Xcode Build Phases. SPM изисква ръчно свързване на Kotlin framework чрез 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.