CocoaPods Plugin — ce este, plugin pentru KMM și configurare

Ce este CocoaPods Plugin?

CocoaPods Plugin (cunoscut și ca kotlin.cocoapods) — este pluginul oficial JetBrains pentru integrarea CocoaPods cu Kotlin Multiplatform Mobile. Pluginul face parte din Kotlin Gradle DSL și se configurează direct în build.gradle.kts al modulului KMM. Acesta automatizează crearea și menținerea Podfile, generarea .xcworkspace și gestionarea dependențelor pod-urilor, eliberând dezvoltatorul de configurarea manuală a proiectului Xcode.

Înainte de apariția CocoaPods Plugin, dezvoltatorii KMM erau forțați să creeze manual Podfile, să ruleze pod install, să configureze bridge-header-uri și să urmărească versiunile pod-urilor separat de dependențele Gradle. Aceasta ducea la desincronizarea versiunilor și dificultăți în pipeline-urile CI/CD. Pluginul a rezolvat aceste probleme, făcând gestionarea dependențelor iOS la fel de simplă ca gestionarea dependențelor Gradle în modulele Android.

Pluginul suportă atât pod-uri publice din CocoaPods Trunk, cât și pod-uri personalizate din depozite private. Lucrul cu Podspec locale și depozite bazate pe git este, de asemenea, suportat. Pluginul este compatibil cu versiunile Kotlin 1.6.0 și mai noi și necesită CocoaPods instalat (gem install cocoapods) pe mașina dezvoltatorului.

Cum funcționează CocoaPods Plugin

CocoaPods Plugin funcționează la nivelul grafului de sarcini Gradle, adăugând sarcini specializate pentru lucrul cu CocoaPods. Sarcinile principale includ podInstall (instalarea pod-urilor), podGenXcodeWorkspace (generarea .xcworkspace) și podBuildDebugFramework (construirea versiunii de debug a framework-ului). Pluginul analizează secțiunea cocoapods din build.gradle.kts, creează Podfile pe baza dependențelor declarate și rulează pod install cu parametrii necesari.

Arhitectura pluginului include trei componente: extensia DSL pentru build.gradle.kts, Generatorul Podfile pentru crearea Podfile și Stratul de integrare Xcode pentru configurarea .xcworkspace. Extensia DSL oferă blocul cocoapods { } cu funcții imbricate pod() pentru declararea dependențelor, specRepo() pentru specificarea depozitelor private și framework { } pentru configurarea framework-ului de ieșire. Generatorul Podfile traduce aceste declarații în sintaxa Ruby inteligibilă pentru 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"
        }
    }
}

Ciclul de viață al sarcinii podInstall

La executarea podInstall, pluginul generează succesiv: Podfile în rădăcina proiectului, rulează pod install prin linia de comandă, generează .xcworkspace, verifică conformitatea versiunilor pod-urilor cu cele declarate și salvează în cache Podfile.lock. La reexecutare fără modificări în configurare, podInstall este omis dacă Podfile.lock nu s-a modificat. Aceasta economisește timp în CI/CD, unde podInstall poate dura până la 2-3 minute pentru o instalare curată.

Configurarea CocoaPods Plugin în proiectul KMM

Pentru configurarea CocoaPods Plugin trebuie executați câțiva pași. Instalarea CocoaPods pe mașina dezvoltatorului (gem install cocoapods) este o condiție obligatorie. Apoi, în build.gradle.kts al modulului shared se adaugă blocul cocoapods { } cu configurarea framework-ului și a dependențelor. După configurare, trebuie executată sarcina podInstall, care va crea Podfile și va instala pod-urile. .xcworkspace generat va fi amplasat în rădăcina proiectului lângă Podfile.

Pluginul se integrează cu Fazele de construire Xcode. La compilarea aplicației iOS, Xcode rulează embedAndSignAppleFrameworkForXcode — o sarcină care copiază framework-ul Kotlin/Native în pachetul aplicației. CocoaPods Plugin adaugă această fază de construire automat la generarea .xcworkspace. Dacă .xcworkspace a fost generat, acesta trebuie deschis în loc de .xcodeproj pentru compilarea corectă cu dependențele pod-urilor.

Exemple de cod: configurarea pod-urilor

Să examinăm diferite scenarii de declarare a pod-urilor în CocoaPods Plugin. Cazul de bază — conectarea unui pod public din CocoaPods Trunk cu specificarea versiunii. Scenarii mai complexe includ utilizarea podspec personalizate, pod-uri locale și pod-uri din depozite git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Pod public din CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Versiune personalizată cu operator
        pod("SnapKit") { version = "~> 5.6" }

        // Pod din depozit privat
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Pod local cu cale
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // Pod din depozit git
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

Conectarea pod-urilor este doar o parte a configurării. Pluginul permite, de asemenea, exportarea dependențelor din alte module Kotlin în framework-ul iOS. Funcția export(project(":core")) indică faptul că toate API-urile publice ale modulului :core trebuie să fie accesibile din header-ul Objective-C al framework-ului generat. Acest lucru este necesar atunci când codul Kotlin comun utilizează clase din alt modul și acestea trebuie să fie accesibile din Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Exportă module în framework-ul iOS
        export(project(":network"))
        export(project(":domain"))

        // Legare statică sau dinamică
        isStatic = true
    }

    // Pod necesar pentru modulele exportate
    pod("Moya") { version = "15.0" }
}

Compilare și testare

După configurare, trebuie executat podInstall pentru generarea Podfile și instalarea dependențelor. Apoi, .xcworkspace generat se deschide în Xcode, unde se poate compila aplicația în mod standard. Pentru CI/CD, trebuie să vă asigurați că CocoaPods și Ruby sunt instalate pe mașina de compilare. Pluginul suportă flag-ul --no-daemon pentru lucrul în mediul CI.

// Instalarea pod-urilor generează Podfile + xcworkspace
./gradlew :shared:podInstall

// Construiește framework de debug pentru testare
./gradlew :shared:podBuildDebugFramework

// Compilare iOS completă din linia de comandă
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — un manager de dependențe alternativ de la Apple, care câștigă popularitate și înlocuiește treptat CocoaPods în comunitatea iOS. Cu toate acestea, CocoaPods Plugin rămâne relevant din mai multe motive: SPM nu suportă framework-uri dinamice în contextul KMM, iar integrarea framework-ului Kotlin/Native prin SPM necesită configurare suplimentară. CocoaPods Plugin oferă o cale de integrare mai matură și mai bine documentată.

Comparația CocoaPods Plugin și integrării directe prin SPM arată că primul câștigă în automatizare, iar al doilea — în suportul nativ Apple. CocoaPods Plugin generează automat Podfile, gestionează versiunile și configurează fazele de construire Xcode. SPM necesită conectarea manuală a framework-ului Kotlin prin Package.swift, ceea ce este mai dificil de întreținut pentru proiecte KMM mari. JetBrains lucrează la suportul SPM pentru Kotlin/Native, dar până în 2025 integrarea SPM rămâne experimentală.

Probleme tipice și soluții

La utilizarea CocoaPods Plugin, dezvoltatorii KMM se confruntă cu câteva probleme tipice. Conflictul de versiuni ale pod-urilor — cea mai frecventă problemă, când două pod-uri necesită versiuni diferite ale aceleiași dependențe. Soluția este specificarea explicită a versiunii dependenței conflictuale prin pod("Dependency") { version = "x.x" }. Al doilea caz frecvent — incompatibilitatea versiunilor, când un pod necesită un iOS SDK mai nou decât versiunea minimă a proiectului KMM.

Probleme cu .xcworkspace apar dacă se deschide .xcodeproj în loc de .xcworkspace după configurarea pluginului. Pluginul avertizează despre aceasta în logurile podInstall. O altă eroare frecventă — lipsa CocoaPods pe mașina dezvoltatorului. Pluginul verifică prezența comenzii pod înainte de a rula podInstall și afișează un mesaj de eroare inteligibil. Pentru CI/CD, trebuie instalat CocoaPods: gem install cocoapods.

// Rezolvă conflictul de versiuni
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Rezolvă conflictul explicit
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Verifică instalarea CocoaPods prin Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Versiunea CocoaPods: $result")
    }
}

Depanarea podInstall

Dacă podInstall se termină cu eroare, utilizați flag-ul --info pentru ieșire detaliată: ./gradlew podInstall --info. Pluginul înregistrează fiecare pas: generarea Podfile, rularea pod install, analizarea Podfile.lock. Cel mai frecvent, erorile sunt legate de probleme de rețea (indisponibilitatea CocoaPods Trunk) sau sintaxa incorectă a Podfile. În astfel de cazuri, încercați să rulați pod install manual în rădăcina proiectului pentru a obține un mesaj de eroare mai detaliat de la CocoaPods.