CocoaPods Plugin — mi ez, plugin KMM-hez és konfiguráció

Mi az a CocoaPods Plugin?

CocoaPods Plugin (más néven kotlin.cocoapods) — a JetBrains hivatalos pluginje a CocoaPods Kotlin Multiplatform Mobile-lel való integrálásához. A plugin a Kotlin Gradle DSL része, és közvetlenül a KMM-modul build.gradle.kts fájljában konfigurálható. Automatizálja a Podfile létrehozását és karbantartását, a .xcworkspace generálását és a pod-függőségek kezelését, megszabadítva a fejlesztőt az Xcode-projekt manuális konfigurálásától.

A CocoaPods Plugin megjelenése előtt a KMM-fejlesztők kénytelenek voltak manuálisan létrehozni a Podfile-t, futtatni a pod install-t, konfigurálni a bridge-headereket, és a pod-verziókat a Gradle-függőségektől elkülönítve nyomon követni. Ez verziók eltéréséhez és nehézségekhez vezetett a CI/CD pipeline-okban. A plugin megoldotta ezeket a problémákat, az iOS-függőségek kezelését olyan egyszerűvé téve, mint a Gradle-függőségek kezelése az Android-modulokban.

A plugin támogatja mind a nyilvános podokat a CocoaPods Trunk-ból, mind az egyedi podokat privát tárolókból. A helyi Podspec-kel és git-alapú tárolókkal való munka szintén támogatott. A plugin kompatibilis a Kotlin 1.6.0 és újabb verzióival, valamint telepített CocoaPods-t (gem install cocoapods) igényel a fejlesztő gépén.

Hogyan működik a CocoaPods Plugin

CocoaPods Plugin a Gradle feladatgráf szintjén működik, speciális feladatokat hozzáadva a CocoaPods-szal való munkához. A fő feladatok közé tartozik a podInstall (podok telepítése), a podGenXcodeWorkspace (.xcworkspace generálása) és a podBuildDebugFramework (a keretrendszer debug verziójának építése). A plugin elemzi a cocoapods szakaszt a build.gradle.kts-ben, létrehozza a Podfile-t a deklarált függőségek alapján, és elindítja a pod install-t a szükséges paraméterekkel.

A plugin architektúrája három összetevőből áll: DSL-bővítmény a build.gradle.kts számára, Podfile generátor a Podfile létrehozásához és Xcode integrációs réteg a .xcworkspace konfigurálásához. A DSL-bővítmény biztosítja a cocoapods { } blokkot a beágyazott pod() függvényekkel a függőségek deklarálásához, a specRepo() a privát tárolók megadásához, és a framework { } a kimeneti keretrendszer konfigurálásához. A Podfile generátor lefordítja ezeket a deklarációkat a CocoaPods számára érthető Ruby szintaxisra.

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"
        }
    }
}

A podInstall feladat életciklusa

A podInstall végrehajtásakor a plugin egymás után: létrehozza a Podfile-t a projekt gyökerében, elindítja a pod install-t a parancssoron keresztül, legenerálja a .xcworkspace-t, ellenőrzi a pod-verziók megfelelését a deklaráltaknak, és elmenti a Podfile.lock-ot. Ismételt futtatáskor, ha a konfiguráció nem változott, a podInstall kimarad, ha a Podfile.lock nem módosult. Ez időt takarít meg a CI/CD-ben, ahol a pod install akár 2-3 percet is igénybe vehet egy tiszta telepítésnél.

A CocoaPods Plugin beállítása KMM-projektben

A CocoaPods Plugin beállításához több lépést kell végrehajtani. A CocoaPods telepítése a fejlesztő gépén (gem install cocoapods) kötelező feltétel. Ezután a shared modul build.gradle.kts fájljában hozzáadásra kerül a cocoapods { } blokk a keretrendszer és a függőségek konfigurációjával. A konfiguráció után végre kell hajtani a podInstall feladatot, amely létrehozza a Podfile-t és telepíti a podokat. A generált .xcworkspace a projekt gyökerében található a Podfile mellett.

A plugin integrálódik az Xcode Build Phases-szel. Az iOS alkalmazás építésekor az Xcode elindítja az embedAndSignAppleFrameworkForXcode feladatot, amely átmásolja a Kotlin/Native keretrendszert az alkalmazás csomagjába. A CocoaPods Plugin automatikusan hozzáadja ezt a build phase-t a .xcworkspace generálásakor. Ha a .xcworkspace generálva lett, azt kell megnyitni a .xcodeproj helyett a pod-függőségekkel való helyes fordítás érdekében.

Kódpéldák: podok konfigurálása

Tekintsük át a podok deklarálásának különböző forgatókönyveit a CocoaPods Pluginban. Az alapeset — nyilvános pod csatlakoztatása a CocoaPods Trunk-ból verzió megadásával. Az összetettebb forgatókönyvek közé tartozik az egyedi podspec, a helyi podok és a git-tárolókból származó podok használata.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Nyilvános pod a CocoaPods Trunk-ból
        pod("Alamofire") { version = "5.9.0" }

        // Egyedi verzió operátorral
        pod("SnapKit") { version = "~> 5.6" }

        // Pod privát tárolóból
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Helyi pod elérési úttal
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // Pod git tárolóból
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

A podok csatlakoztatása csak egy része a konfigurációnak. A plugin lehetővé teszi a függőségek exportálását más Kotlin-modulokból az iOS keretrendszerbe. Az export(project(":core")) függvény jelzi, hogy a :core modul összes nyilvános API-jának elérhetőnek kell lennie a generált keretrendszer Objective-C fejlécéből. Ez akkor szükséges, amikor a közös Kotlin-kód egy másik modul osztályait használja, és azoknak elérhetőnek kell lenniük Swift-ből.

cocoapods {
    framework {
        baseName = "Shared"
        // Modulok exportálása iOS keretrendszerbe
        export(project(":network"))
        export(project(":domain"))

        // Statikus vagy dinamikus kapcsolódás
        isStatic = true
    }

    // Pod szükséges az exportált modulokhoz
    pod("Moya") { version = "15.0" }
}

Építés és tesztelés

A konfiguráció után végre kell hajtani a podInstall feladatot a Podfile létrehozásához és a függőségek telepítéséhez. Ezután a generált .xcworkspace megnyílik az Xcode-ban, ahol az alkalmazás a szokásos módon építhető. A CI/CD számára győződjön meg arról, hogy a CocoaPods és a Ruby telepítve van a build-gépen. A plugin támogatja a --no-daemon kapcsolót a CI környezetben való munkához.

// Podok telepítése Podfile + xcworkspace fájlokat generál
./gradlew :shared:podInstall

// Debug keretrendszer építése teszteléshez
./gradlew :shared:podBuildDebugFramework

// Teljes iOS build parancssorból
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — egy alternatív függőségkezelő az Apple-től, amely egyre népszerűbb, és fokozatosan kiszorítja a CocoaPods-ot az iOS közösségből. A CocoaPods Plugin azonban több okból is releváns marad: az SPM nem támogatja a dinamikus keretrendszereket KMM-kontextusban, és a Kotlin/Native keretrendszer SPM-en keresztüli integrálása további konfigurációt igényel. A CocoaPods Plugin érettebb és dokumentáltabb integrációs utat biztosít.

Összehasonlítás a CocoaPods Plugin és az SPM-en keresztüli közvetlen integráció között azt mutatja, hogy az első az automatizálásban, a második pedig az Apple natív támogatásában győz. A CocoaPods Plugin automatikusan generálja a Podfile-t, kezeli a verziókat és konfigurálja az Xcode Build Phases-okat. Az SPM a Kotlin keretrendszer manuális csatlakoztatását igényli a Package.swift-en keresztül, ami nagy KMM-projektek esetén nehezebben karbantartható. A JetBrains az SPM támogatáson dolgozik a Kotlin/Native számára, de 2025-ig az SPM-integráció kísérleti jellegű marad.

Gyakori problémák és megoldások

A CocoaPods Plugin használatakor a KMM-fejlesztők számos gyakori problémába ütköznek. Pod-verziók ütközése — a leggyakoribb probléma, amikor két pod ugyanazon függőség különböző verzióját igényli. A megoldás az ütköző függőség verziójának explicit megadása a pod("Dependency") { version = "x.x" } segítségével. A második gyakori eset — verzió-inkompatibilitás, amikor egy pod újabb iOS SDK-t igényel, mint a KMM-projekt minimális verziója.

Problémák a .xcworkspace-szel akkor merülnek fel, ha a plugin konfigurálása után a .xcodeproj-t nyitják meg a .xcworkspace helyett. A plugin figyelmeztet erről a podInstall naplókban. Egy másik gyakori hiba — a CocoaPods hiánya a fejlesztő gépén. A plugin ellenőrzi a pod parancs meglétét a podInstall elindítása előtt, és érthető hibaüzenetet jelenít meg. CI/CD számára telepítse a CocoaPods-t: gem install cocoapods.

// Verzióütközés feloldása
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Ütközés explicit feloldása
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// CocoaPods telepítés ellenőrzése Gradle-en keresztül
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods verzió: $result")
    }
}

A podInstall hibakeresése

Ha a podInstall hibával végződik, használja a --info kapcsolót a részletes kimenethez: ./gradlew podInstall --info. A plugin naplózza az összes lépést: Podfile generálása, pod install futtatása, Podfile.lock elemzése. A hibák leggyakrabban hálózati problémákhoz (CocoaPods Trunk elérhetetlensége) vagy a Podfile hibás szintaxisához kapcsolódnak. Ilyen esetekben próbálja meg manuálisan futtatni a pod install-t a projekt gyökerében, hogy részletesebb hibaüzenetet kapjon a CocoaPods-tól.