CocoaPods Plugin — co to je, plugin pro KMM a konfigurace

Co je CocoaPods Plugin?

CocoaPods Plugin (také známý jako kotlin.cocoapods) — je oficiální plugin JetBrains pro integraci CocoaPods s Kotlin Multiplatform Mobile. Plugin je součástí Kotlin Gradle DSL a konfiguruje se přímo v build.gradle.kts KMM modulu. Automatizuje vytváření a údržbu Podfile, generování .xcworkspace a správu pod závislostí, čímž osvobozuje vývojáře od ruční konfigurace Xcode projektu.

Před příchodem CocoaPods Plugin byli KMM vývojáři nuceni ručně vytvářet Podfile, spouštět pod install, konfigurovat bridge-headery a sledovat verze podů odděleně od Gradle závislostí. To vedlo k desynchronizaci verzí a potížím v CI/CD pipeline. Plugin tyto problémy vyřešil, čímž učinil správu iOS závislostí stejně jednoduchou jako správu Gradle závislostí v Android modulech.

Plugin podporuje jak veřejné pody z CocoaPods Trunk, tak vlastní pody z privátních repozitářů. Práce s lokálními Podspec a repozitáři založenými na git je také podporována. Plugin je kompatibilní s verzemi Kotlin 1.6.0 a vyššími a vyžaduje nainstalované CocoaPods (gem install cocoapods) na počítači vývojáře.

Jak funguje CocoaPods Plugin

CocoaPods Plugin pracuje na úrovni grafu úloh Gradle, přidává specializované úlohy pro práci s CocoaPods. Hlavní úlohy zahrnují podInstall (instalace podů), podGenXcodeWorkspace (generování .xcworkspace) a podBuildDebugFramework (sestavení debug verze frameworku). Plugin analyzuje sekci cocoapods v build.gradle.kts, vytváří Podfile na základě deklarovaných závislostí a spouští pod install s potřebnými parametry.

Architektura pluginu zahrnuje tři komponenty: DSL rozšíření pro build.gradle.kts, Podfile generátor pro vytváření Podfile a Xcode integrační vrstvu pro konfiguraci .xcworkspace. DSL rozšíření poskytuje blok cocoapods { } s vnořenými funkcemi pod() pro deklarování závislostí, specRepo() pro určení privátních repozitářů a framework { } pro konfiguraci výstupního frameworku. Podfile generátor překládá tyto deklarace do syntaxe Ruby srozumitelné pro 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"
        }
    }
}

Životní cyklus úlohy podInstall

Při provádění podInstall plugin postupně: generuje Podfile v kořenu projektu, spouští pod install přes příkazový řádek, generuje .xcworkspace, kontroluje shodu verzí podů s deklarovanými a ukládá do mezipaměti Podfile.lock. Při opětovném spuštění bez změn v konfiguraci je podInstall přeskočen, pokud se Podfile.lock nezměnil. To šetří čas v CI/CD, kde podInstall může trvat až 2-3 minuty při čisté instalaci.

Konfigurace CocoaPods Plugin v KMM projektu

Pro konfiguraci CocoaPods Plugin je třeba provést několik kroků. Instalace CocoaPods na počítači vývojáře (gem install cocoapods) je povinnou podmínkou. Poté se v build.gradle.kts shared modulu přidá blok cocoapods { } s konfigurací frameworku a závislostí. Po konfiguraci je třeba spustit úlohu podInstall, která vytvoří Podfile a nainstaluje pody. Generovaný .xcworkspace bude umístěn v kořenu projektu vedle Podfile.

Plugin se integruje s Xcode Build Phases. Při sestavování iOS aplikace Xcode spouští embedAndSignAppleFrameworkForXcode — úlohu, která kopíruje Kotlin/Native framework do balíčku aplikace. CocoaPods Plugin přidává tuto build phase automaticky při generování .xcworkspace. Pokud byl .xcworkspace vygenerován, je třeba jej otevírat namísto .xcodeproj pro korektní kompilaci s pod závislostmi.

Příklady kódu: konfigurace podů

Podívejme se na různé scénáře deklarování podů v CocoaPods Plugin. Základní případ — připojení veřejného podu z CocoaPods Trunk s uvedením verze. Složitější scénáře zahrnují použití vlastních podspec, lokálních podů a podů z git repozitářů.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Veřejný pod z CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Vlastní verze s operátorem
        pod("SnapKit") { version = "~> 5.6" }

        // Pod z privátního repozitáře
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Lokální pod s cestou
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // Pod z git repozitáře
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

Připojování podů je jen část konfigurace. Plugin také umožňuje exportovat závislosti z jiných Kotlin modulů do iOS frameworku. Funkce export(project(":core")) udává, že všechna veřejná API modulu :core musí být přístupná z Objective-C hlavičky generovaného frameworku. To je nezbytné, když společný Kotlin kód používá třídy z jiného modulu a ty musí být přístupné z Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Exportovat moduly do iOS frameworku
        export(project(":network"))
        export(project(":domain"))

        // Statické nebo dynamické propojení
        isStatic = true
    }

    // Pod vyžadovaný pro exportované moduly
    pod("Moya") { version = "15.0" }
}

Sestavení a testování

Po konfiguraci je třeba spustit podInstall pro generování Podfile a instalaci závislostí. Poté se generovaný .xcworkspace otevře v Xcode, kde lze aplikaci sestavit standardním způsobem. Pro CI/CD je třeba zajistit, aby byly CocoaPods a Ruby nainstalovány na sestavovacím počítači. Plugin podporuje přepínač --no-daemon pro práci v CI prostředí.

// Instalace podů generuje Podfile + xcworkspace
./gradlew :shared:podInstall

// Sestavit debug framework pro testování
./gradlew :shared:podBuildDebugFramework

// Plné iOS sestavení z příkazového řádku
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — alternativní správce závislostí od Apple, který získává na popularitě a postupně vytlačuje CocoaPods v iOS komunitě. CocoaPods Plugin však zůstává relevantní z několika důvodů: SPM nepodporuje dynamické frameworky v KMM kontextu a integrace Kotlin/Native frameworku přes SPM vyžaduje dodatečnou konfiguraci. CocoaPods Plugin poskytuje zralejší a zdokumentovanější cestu integrace.

Srovnání CocoaPods Plugin a přímé integrace přes SPM ukazuje, že první vítězí v automatizaci a druhý — v nativní podpoře Apple. CocoaPods Plugin automaticky generuje Podfile, spravuje verze a konfiguruje Xcode Build Phases. SPM vyžaduje ruční připojení Kotlin frameworku přes Package.swift, což je náročnější na údržbu pro velké KMM projekty. JetBrains pracuje na podpoře SPM pro Kotlin/Native, ale do roku 2025 zůstává SPM integrace experimentální.

Typické problémy a řešení

Při používání CocoaPods Plugin se KMM vývojáři setkávají s několika typickými problémy. Konflikt verzí podů — nejčastější problém, když dva pody vyžadují různé verze stejné závislosti. Řešením je explicitní uvedení verze konfliktní závislosti přes pod("Dependency") { version = "x.x" }. Druhý častý případ — nekompatibilita verzí, když pod vyžaduje novější iOS SDK než minimální verze KMM projektu.

Problémy s .xcworkspace vznikají, pokud se po konfiguraci pluginu otevře .xcodeproj místo .xcworkspace. Plugin na to upozorňuje v logách podInstall. Další častá chyba — absence CocoaPods na počítači vývojáře. Plugin kontroluje přítomnost příkazu pod před spuštěním podInstall a zobrazuje srozumitelnou chybovou zprávu. Pro CI/CD je třeba nainstalovat CocoaPods: gem install cocoapods.

// Vyřešit konflikt verzí
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Explicitně vyřešit konflikt
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Zkontrolovat instalaci CocoaPods přes Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Verze CocoaPods: $result")
    }
}

Ladění podInstall

Pokud podInstall skončí chybou, použijte přepínač --info pro podrobný výstup: ./gradlew podInstall --info. Plugin protokoluje každý krok: generování Podfile, spuštění pod install, analýzu Podfile.lock. Nejčastěji chyby souvisejí se síťovými problémy (nedostupnost CocoaPods Trunk) nebo nesprávnou syntaxí Podfile. V takových případech zkuste spustit pod install ručně v kořenu projektu pro získání podrobnější chybové zprávy od CocoaPods.