CocoaPods Plugin — wat is het, plugin voor KMM en configuratie

Wat is CocoaPods Plugin?

CocoaPods Plugin (ook bekend als kotlin.cocoapods) — is de officiële JetBrains-plugin voor integratie van CocoaPods met Kotlin Multiplatform Mobile. De plugin maakt deel uit van Kotlin Gradle DSL en wordt rechtstreeks geconfigureerd in build.gradle.kts van de KMM-module. Het automatiseert het aanmaken en onderhouden van Podfile, het genereren van .xcworkspace en het beheren van pod-afhankelijkheden, waardoor de ontwikkelaar wordt ontlast van handmatige Xcode-projectconfiguratie.

Vóór de komst van CocoaPods Plugin waren KMM-ontwikkelaars gedwongen om handmatig Podfile aan te maken, pod install uit te voeren, bridge-headers te configureren en pod-versies apart van Gradle-afhankelijkheden bij te houden. Dit leidde tot desynchronisatie van versies en problemen in CI/CD-pijplijnen. De plugin loste deze problemen op door het beheer van iOS-afhankelijkheden net zo eenvoudig te maken als het beheer van Gradle-afhankelijkheden in Android-modules.

De plugin ondersteunt zowel openbare pods van CocoaPods Trunk als aangepaste pods uit privé-repositories. Werken met lokale Podspec en git-gebaseerde repositories wordt ook ondersteund. De plugin is compatibel met Kotlin-versies 1.6.0 en hoger, en vereist geïnstalleerde CocoaPods (gem install cocoapods) op de machine van de ontwikkelaar.

Hoe werkt CocoaPods Plugin

CocoaPods Plugin werkt op het niveau van de Gradle-taakgrafiek en voegt gespecialiseerde taken toe voor het werken met CocoaPods. De belangrijkste taken zijn podInstall (installatie van pods), podGenXcodeWorkspace (genereren van .xcworkspace) en podBuildDebugFramework (bouwen van de debug-versie van het framework). De plugin analyseert de cocoapods-sectie in build.gradle.kts, maakt Podfile op basis van gedeclareerde afhankelijkheden en voert pod install uit met de vereiste parameters.

De architectuur van de plugin omvat drie componenten: DSL-extensie voor build.gradle.kts, Podfile Generator voor het maken van Podfile en Xcode-integratielaag voor het configureren van .xcworkspace. De DSL-extensie biedt het cocoapods { }-blok met geneste pod()-functies voor het declareren van afhankelijkheden, specRepo() voor het specificeren van privé-repositories en framework { } voor het configureren van het uitvoerframework. De Podfile Generator vertaalt deze declaraties naar Ruby-syntaxis die begrijpelijk is voor 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"
        }
    }
}

Levenscyclus van de podInstall-taak

Bij het uitvoeren van podInstall genereert de plugin achtereenvolgens: Podfile in de hoofdmap van het project, voert pod install uit via de opdrachtregel, genereert .xcworkspace, controleert de overeenstemming van pod-versies met de gedeclareerde versies en cachet Podfile.lock. Bij herhaalde uitvoering zonder wijzigingen in de configuratie wordt podInstall overgeslagen als Podfile.lock niet is gewijzigd. Dit bespaart tijd in CI/CD, waar pod install 2-3 minuten kan duren voor een schone installatie.

Configuratie van CocoaPods Plugin in een KMM-project

Voor het configureren van CocoaPods Plugin moeten verschillende stappen worden uitgevoerd. Installatie van CocoaPods op de ontwikkelaarsmachine (gem install cocoapods) is een verplichte voorwaarde. Vervolgens wordt in build.gradle.kts van de shared-module het cocoapods { }-blok toegevoegd met de configuratie van het framework en de afhankelijkheden. Na configuratie moet de podInstall-taak worden uitgevoerd, die Podfile aanmaakt en de pods installeert. De gegenereerde .xcworkspace bevindt zich in de hoofdmap van het project naast Podfile.

De plugin integreert met Xcode Build Phases. Tijdens het bouwen van de iOS-app voert Xcode embedAndSignAppleFrameworkForXcode uit — een taak die het Kotlin/Native-framework naar het app-bundle kopieert. CocoaPods Plugin voegt deze build-phase automatisch toe bij het genereren van .xcworkspace. Als .xcworkspace is gegenereerd, moet deze worden geopend in plaats van .xcodeproj voor correcte compilatie met pod-afhankelijkheden.

Codevoorbeelden: configuratie van pods

Laten we verschillende scenario's bekijken voor het declareren van pods in CocoaPods Plugin. Het basisscenario — aansluiten van een openbare pod van CocoaPods Trunk met versieopgave. Complexere scenario's omvatten het gebruik van aangepaste podspec, lokale pods en pods uit git-repositories.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Openbare pod van CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Aangepaste versie met operator
        pod("SnapKit") { version = "~> 5.6" }

        // Pod van privé-repository
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Lokale pod met pad
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Het aansluiten van pods is slechts een deel van de configuratie. De plugin maakt het ook mogelijk om afhankelijkheden uit andere Kotlin-modules naar het iOS-framework te exporteren. De functie export(project(":core")) geeft aan dat alle openbare API's van de :core-module toegankelijk moeten zijn vanuit de Objective-C-header van het gegenereerde framework. Dit is nodig wanneer gedeelde Kotlin-code klassen uit een andere module gebruikt en deze toegankelijk moeten zijn vanuit Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Modules exporteren naar iOS-framework
        export(project(":network"))
        export(project(":domain"))

        // Statische of dynamische koppeling
        isStatic = true
    }

    // Pod vereist voor geëxporteerde modules
    pod("Moya") { version = "15.0" }
}

Bouwen en testen

Na het configureren moet podInstall worden uitgevoerd om Podfile te genereren en afhankelijkheden te installeren. Vervolgens wordt de gegenereerde .xcworkspace geopend in Xcode, waar de app op de standaard manier kan worden gebouwd. Voor CI/CD moet u ervoor zorgen dat CocoaPods en Ruby zijn geïnstalleerd op de build-machine. De plugin ondersteunt de vlag --no-daemon voor werken in een CI-omgeving.

// Pods installeren genereert Podfile + xcworkspace
./gradlew :shared:podInstall

// Debug-framework bouwen voor testen
./gradlew :shared:podBuildDebugFramework

// Volledige iOS-build vanaf de opdrachtregel
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — een alternatieve afhankelijkheidsbeheerder van Apple, die aan populariteit wint en geleidelijk CocoaPods verdringt in de iOS-gemeenschap. CocoaPods Plugin blijft echter om verschillende redenen relevant: SPM ondersteunt geen dynamische frameworks in KMM-context en integratie van het Kotlin/Native-framework via SPM vereist extra configuratie. CocoaPods Plugin biedt een volwassenere en beter gedocumenteerde integratieroute.

Vergelijking tussen CocoaPods Plugin en directe integratie via SPM laat zien dat de eerste wint op automatisering en de tweede op native Apple-ondersteuning. CocoaPods Plugin genereert automatisch Podfile, beheert versies en configureert Xcode Build Phases. SPM vereist handmatige aansluiting van het Kotlin-framework via Package.swift, wat moeilijker te onderhouden is voor grote KMM-projecten. JetBrains werkt aan SPM-ondersteuning voor Kotlin/Native, maar tot 2025 blijft SPM-integratie experimenteel.

Veelvoorkomende problemen en oplossingen

Bij het gebruik van CocoaPods Plugin komen KMM-ontwikkelaars verschillende veelvoorkomende problemen tegen. Versieconflict van pods — het meest voorkomende probleem, wanneer twee pods verschillende versies van dezelfde afhankelijkheid vereisen. De oplossing is het expliciet specificeren van de versie van de conflicterende afhankelijkheid via pod("Dependency") { version = "x.x" }. Het tweede veelvoorkomende geval — versie-incompatibiliteit, wanneer een pod een nieuwere iOS SDK vereist dan de minimale versie van het KMM-project.

Problemen met .xcworkspace ontstaan wanneer .xcodeproj wordt geopend in plaats van .xcworkspace na configuratie van de plugin. De plugin waarschuwt hiervoor in de podInstall-logboeken. Een andere veelvoorkomende fout — het ontbreken van CocoaPods op de ontwikkelaarsmachine. De plugin controleert de aanwezigheid van het pod-commando voordat podInstall wordt uitgevoerd en geeft een duidelijke foutmelding. Voor CI/CD moet CocoaPods worden geïnstalleerd: gem install cocoapods.

// Versieconflict oplossen
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Conflict expliciet oplossen
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// CocoaPods-installatie controleren via Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods-versie: $result")
    }
}

Debuggen van podInstall

Als podInstall eindigt met een fout, gebruik dan de --info-vlag voor gedetailleerde uitvoer: ./gradlew podInstall --info. De plugin logt elke stap: genereren van Podfile, uitvoeren van pod install, parseren van Podfile.lock. Meestal hebben fouten te maken met netwerkproblemen (onbereikbaarheid van CocoaPods Trunk) of onjuiste syntax van Podfile. Probeer in dergelijke gevallen pod install handmatig uit te voeren in de hoofdmap van het project om een gedetailleerdere foutmelding van CocoaPods te krijgen.