CocoaPods Plugin — co to jest, wtyczka do KMM i konfiguracja

Czym jest CocoaPods Plugin?

CocoaPods Plugin (znany również jako kotlin.cocoapods) — to oficjalna wtyczka JetBrains do integracji CocoaPods z Kotlin Multiplatform Mobile. Wtyczka jest częścią Kotlin Gradle DSL i konfigurowana jest bezpośrednio w build.gradle.kts modułu KMM. Automatyzuje tworzenie i utrzymywanie Podfile, generowanie .xcworkspace i zarządzanie zależnościami podów, uwalniając programistę od ręcznej konfiguracji projektu Xcode.

Przed pojawieniem się CocoaPods Plugin, programiści KMM byli zmuszeni ręcznie tworzyć Podfile, uruchamiać pod install, konfigurować bridge-headery i śledzić wersje podów oddzielnie od zależności Gradle. Prowadziło to do desynchronizacji wersji i trudności w pipeline'ach CI/CD. Wtyczka rozwiązała te problemy, czyniąc zarządzanie zależnościami iOS tak prostym, jak zarządzanie zależnościami Gradle w modułach Android.

Wtyczka obsługuje zarówno publiczne pody z CocoaPods Trunk, jak i niestandardowe pody z prywatnych repozytoriów. Obsługiwana jest również praca z lokalnymi Podspec i repozytoriami opartymi na git. Wtyczka jest kompatybilna z wersjami Kotlin 1.6.0 i nowszymi, a także wymaga zainstalowanego CocoaPods (gem install cocoapods) na maszynie programisty.

Jak działa CocoaPods Plugin

CocoaPods Plugin działa na poziomie Gradle task-graph, dodając wyspecjalizowane zadania do pracy z CocoaPods. Główne zadania obejmują podInstall (instalacja podów), podGenXcodeWorkspace (generowanie .xcworkspace) i podBuildDebugFramework (budowanie debugowej wersji frameworka). Wtyczka analizuje sekcję cocoapods w build.gradle.kts, tworzy Podfile na podstawie zadeklarowanych zależności i uruchamia pod install z odpowiednimi parametrami.

Architektura wtyczki obejmuje trzy komponenty: rozszerzenie DSL dla build.gradle.kts, generator Podfile do tworzenia Podfile i warstwę integracji Xcode do konfiguracji .xcworkspace. Rozszerzenie DSL udostępnia blok cocoapods { } z zagnieżdżonymi funkcjami pod() do deklarowania zależności, specRepo() do wskazywania prywatnych repozytoriów oraz framework { } do konfiguracji wyjściowego frameworka. Generator Podfile tłumaczy te deklaracje na składnię Ruby zrozumiałą dla 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"
        }
    }
}

Cykl życia zadania podInstall

Podczas wykonywania podInstall, wtyczka kolejno: generuje Podfile w katalogu głównym projektu, uruchamia pod install przez linię poleceń, generuje .xcworkspace, sprawdza zgodność wersji podów zadeklarowanym i buforuje Podfile.lock. Przy ponownym uruchomieniu bez zmian w konfiguracji, podInstall jest pomijany, jeśli Podfile.lock nie uległ zmianie. Oszczędza to czas w CI/CD, gdzie pod install może zajmować do 2–3 minut przy czystej instalacji.

Konfiguracja CocoaPods Plugin w projekcie KMM

Do konfiguracji CocoaPods Plugin należy wykonać kilka kroków. Instalacja CocoaPods na maszynie programisty (gem install cocoapods) jest warunkiem obowiązkowym. Następnie w build.gradle.kts modułu shared dodawany jest blok cocoapods { } z konfiguracją frameworka i zależności. Po konfiguracji należy wykonać zadanie podInstall, które utworzy Podfile i zainstaluje pody. Wygenerowany .xcworkspace będzie znajdować się w katalogu głównym projektu obok Podfile.

Wtyczka integruje się z fazami budowania Xcode. Podczas kompilacji aplikacji iOS, Xcode uruchamia embedAndSignAppleFrameworkForXcode — zadanie, które kopiuje framework Kotlin/Native do pakietu aplikacji. CocoaPods Plugin dodaje tę fazę budowania automatycznie podczas generowania .xcworkspace. Jeśli .xcworkspace został wygenerowany, należy go otwierać zamiast .xcodeproj dla poprawnej kompilacji z zależnościami podów.

Przykłady kodu: konfiguracja podów

Rozważmy różne scenariusze deklarowania podów w CocoaPods Plugin. Podstawowy przypadek — podłączenie publicznego poda z CocoaPods Trunk z określeniem wersji. Bardziej złożone scenariusze obejmują użycie niestandardowych podspec, lokalnych podów i podów z repozytoriów git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Publiczny pod z CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Niestandardowa wersja z operatorem
        pod("SnapKit") { version = "~> 5.6" }

        // Pod z prywatnego repozytorium
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Lokalny pod ze ścieżką
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Podłączanie podów to tylko część konfiguracji. Wtyczka umożliwia również eksportowanie zależności z innych modułów Kotlin do frameworka iOS. Funkcja export(project(":core")) wskazuje, że wszystkie publiczne API modułu :core powinny być dostępne z nagłówka Objective-C wygenerowanego frameworka. Jest to konieczne, gdy współny kod Kotlin używa klas z innego modułu i muszą one być dostępne z Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Eksportuj moduły do frameworka iOS
        export(project(":network"))
        export(project(":domain"))

        // Łączenie statyczne lub dynamiczne
        isStatic = true
    }

    // Pod wymagany dla eksportowanych modułów
    pod("Moya") { version = "15.0" }
}

Kompilacja i testowanie

Po skonfigurowaniu należy wykonać podInstall w celu wygenerowania Podfile i instalacji zależności. Następnie wygenerowany .xcworkspace otwierany jest w Xcode, gdzie można skompilować aplikację standardowym sposobem. Dla CI/CD należy upewnić się, że na maszynie kompilacyjnej zainstalowane są CocoaPods i Ruby. Wtyczka obsługuje flagę --no-daemon do pracy w środowisku CI.

// Instalacja podów generuje Podfile + xcworkspace
./gradlew :shared:podInstall

// Zbuduj debug framework do testowania
./gradlew :shared:podBuildDebugFramework

// Pełna kompilacja iOS z linii poleceń
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — alternatywny menedżer zależności od Apple, który zyskuje na popularności i stopniowo wypiera CocoaPods w społeczności iOS. Jednak CocoaPods Plugin pozostaje aktualny z kilku powodów: SPM nie obsługuje dynamicznych frameworków w kontekście KMM, a integracja frameworka Kotlin/Native przez SPM wymaga dodatkowej konfiguracji. CocoaPods Plugin zapewnia bardziej dojrzałą i udokumentowaną ścieżkę integracji.

Porównanie CocoaPods Plugin i bezpośredniej integracji przez SPM pokazuje, że pierwszy wygrywa w automatyzacji, a drugi — w natywnym wsparciu Apple. CocoaPods Plugin automatycznie generuje Podfile, zarządza wersjami i konfiguruje fazy budowania Xcode. SPM wymaga ręcznego podłączenia frameworka Kotlin przez Package.swift, co jest trudniejsze w utrzymaniu dla dużych projektów KMM. JetBrains pracuje nad wsparciem SPM dla Kotlin/Native, ale na 2025 rok integracja SPM pozostaje eksperymentalna.

Typowe problemy i rozwiązania

Podczas korzystania z CocoaPods Plugin, programiści KMM spotykają się z kilkoma typowymi problemami. Konflikt wersji podów — najczęstszy problem, gdy dwa pody wymagają różnych wersji tej samej zależności. Rozwiązaniem jest jawne określenie wersji konfliktującej zależności przez pod("Dependency") { version = "x.x" }. Drugi częsty przypadek — niezgodność wersji, gdy pod wymaga nowszego iOS SDK niż minimalna wersja projektu KMM.

Problemy z .xcworkspace występują, jeśli otwiera się .xcodeproj zamiast .xcworkspace po konfiguracji wtyczki. Wtyczka ostrzega o tym w logach podInstall. Inny częsty błąd — brak CocoaPods na maszynie programisty. Wtyczka sprawdza obecność polecenia pod przed uruchomieniem podInstall i wyświetla zrozumiały komunikat błędu. Dla CI/CD należy zainstalować CocoaPods: gem install cocoapods.

// Rozwiąż konflikt wersji
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Rozwiąż konflikt jawnie
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Sprawdź instalację CocoaPods przez Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Wersja CocoaPods: $result")
    }
}

Debugowanie podInstall

Jeśli podInstall kończy się błędem, użyj flagi --info do szczegółowego wyjścia: ./gradlew podInstall --info. Wtyczka loguje każdy krok: generowanie Podfile, uruchomienie pod install, parsowanie Podfile.lock. Najczęściej błędy związane są z problemami sieciowymi (niedostępność CocoaPods Trunk) lub nieprawidłową składnią Podfile. W takich przypadkach spróbuj uruchomić pod install ręcznie w katalogu głównym projektu, aby uzyskać bardziej szczegółowy komunikat błędu od CocoaPods.