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 графа задатака, додајући специјализоване задатке за рад са 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 shared модула додаје блок cocoapods { } са конфигурацијом оквира и зависности. Након подешавања, потребно је извршити задатак podInstall, који ће креирати Podfile и инсталирати подове. Генерисани .xcworkspace ће се налазити у корену пројекта поред Podfile-а.

Плагин се интегрише са Xcode фазама изградње. Приликом компилације iOS апликације, Xcode покреће embedAndSignAppleFrameworkForXcode — задатак који копира Kotlin/Native оквир у пакет апликације. CocoaPods Plugin додаје ову фазу изградње аутоматски приликом генерисања .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 фазе изградње. 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-а.