CocoaPods Plugin — vad är det, plugin för KMM och konfiguration

Vad är CocoaPods Plugin?

CocoaPods Plugin (även känt som kotlin.cocoapods) — är JetBrains officiella plugin för integration av CocoaPods med Kotlin Multiplatform Mobile. Plugin är en del av Kotlin Gradle DSL och konfigureras direkt i build.gradle.kts för KMM-modulen. Den automatiserar skapande och underhåll av Podfile, generering av .xcworkspace och hantering av pod-beroenden, vilket befriar utvecklaren från manuell konfiguration av Xcode-projektet.

Innan CocoaPods Plugin kom till var KMM-utvecklare tvungna att manuellt skapa Podfile, köra pod install, konfigurera bridge-headers och hålla reda på pod-versioner separat från Gradle-beroenden. Detta ledde till avsynkronisering av versioner och svårigheter i CI/CD-pipelines. Plugin löste dessa problem och gjorde hanteringen av iOS-beroenden lika enkel som hanteringen av Gradle-beroenden i Android-moduler.

Plugin stöder både offentliga pods från CocoaPods Trunk och anpassade pods från privata repository. Arbete med lokala Podspec och git-baserade repository stöds också. Plugin är kompatibel med Kotlin-versioner 1.6.0 och senare, och kräver installerad CocoaPods (gem install cocoapods) på utvecklarens maskin.

Hur fungerar CocoaPods Plugin

CocoaPods Plugin arbetar på nivån av Gradle-uppgiftsgrafen och lägger till specialiserade uppgifter för arbete med CocoaPods. Huvuduppgifterna inkluderar podInstall (installation av pods), podGenXcodeWorkspace (generering av .xcworkspace) och podBuildDebugFramework (byggande av debug-version av ramverket). Plugin analyserar cocoapods-sektionen i build.gradle.kts, skapar Podfile baserat på deklarerade beroenden och kör pod install med nödvändiga parametrar.

Pluginens arkitektur består av tre komponenter: DSL-utökning för build.gradle.kts, Podfile-generator för att skapa Podfile och Xcode-integrationslager för konfiguration av .xcworkspace. DSL-utökningen tillhandahåller cocoapods { }-blocket med nästlade pod()-funktioner för att deklarera beroenden, specRepo() för att ange privata repository och framework { } för att konfigurera utmatningsramverket. Podfile-generatorn översätter dessa deklarationer till Ruby-syntax som är begriplig för 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"
        }
    }
}

Livscykel för podInstall-uppgiften

Vid körning av podInstall genererar plugin sekventiellt: Podfile i projektroten, kör pod install via kommandoraden, genererar .xcworkspace, kontrollerar överensstämmelse mellan pod-versioner och deklarerade versioner, och cachar Podfile.lock. Vid omkörning utan ändringar i konfigurationen hoppas podInstall över om Podfile.lock inte har ändrats. Detta sparar tid i CI/CD, där pod Install kan ta upp till 2-3 minuter för en ren installation.

Konfiguration av CocoaPods Plugin i KMM-projekt

För konfiguration av CocoaPods Plugin måste flera steg utföras. Installation av CocoaPods på utvecklarens maskin (gem install cocoapods) är ett obligatoriskt villkor. Sedan läggs cocoapods { }-blocket till i build.gradle.kts för shared-modulen med konfiguration av ramverk och beroenden. Efter konfiguration måste podInstall-uppgiften köras, vilken skapar Podfile och installerar pods. Den genererade .xcworkspace kommer att finnas i projektroten bredvid Podfile.

Plugin integreras med Xcode Build Phases. Vid byggande av iOS-applikationen kör Xcode embedAndSignAppleFrameworkForXcode — en uppgift som kopierar Kotlin/Native-ramverket till applikationspaketet. CocoaPods Plugin lägger till denna byggfas automatiskt vid generering av .xcworkspace. Om .xcworkspace har genererats måste den öppnas istället för .xcodeproj för korrekt kompilering med pod-beroenden.

Kodexempel: konfiguration av pods

Låt oss titta på olika scenarier för deklaration av pods i CocoaPods Plugin. Grundfallet — anslutning av en offentlig pod från CocoaPods Trunk med versionsangivelse. Mer komplexa scenarier inkluderar användning av anpassad podspec, lokala pods och pods från git-repository.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Offentlig pod från CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Anpassad version med operator
        pod("SnapKit") { version = "~> 5.6" }

        // Pod från privat repository
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Lokal pod med sökväg
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Anslutning av pods är bara en del av konfigurationen. Plugin gör det också möjligt att exportera beroenden från andra Kotlin-moduler till iOS-ramverket. Funktionen export(project(":core")) anger att alla offentliga API:er för :core-modulen måste vara tillgängliga från Objective-C-huvudet för det genererade ramverket. Detta är nödvändigt när gemensam Kotlin-kod använder klasser från en annan modul och de måste vara tillgängliga från Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Exportera moduler till iOS-ramverk
        export(project(":network"))
        export(project(":domain"))

        // Statisk eller dynamisk koppling
        isStatic = true
    }

    // Pod som krävs för exporterade moduler
    pod("Moya") { version = "15.0" }
}

Bygga och testa

Efter konfiguration måste podInstall köras för att generera Podfile och installera beroenden. Därefter öppnas den genererade .xcworkspace i Xcode, där applikationen kan byggas på vanligt sätt. För CI/CD, se till att CocoaPods och Ruby är installerade på byggmaskinen. Plugin stöder flaggan --no-daemon för arbete i CI-miljö.

// Installation av pods genererar Podfile + xcworkspace
./gradlew :shared:podInstall

// Bygg debug-ramverk för testning
./gradlew :shared:podBuildDebugFramework

// Fullstänigt iOS-bygge från kommandoraden
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — en alternativ beroendehanterare från Apple, som blir allt populärare och gradvis ersätter CocoaPods i iOS-communityt. CocoaPods Plugin förblir dock relevant av flera anledningar: SPM stöder inte dynamiska ramverk i KMM-sammanhang, och integration av Kotlin/Native-ramverket via SPM kräver ytterligare konfiguration. CocoaPods Plugin tillhandahåller en mer mogen och väldokumenterad integrationsväg.

Jämförelse av CocoaPods Plugin och direkt integration via SPM visar att den första vinner i automatisering och den andra i native Apple-stöd. CocoaPods Plugin genererar automatiskt Podfile, hanterar versioner och konfigurerar Xcode Build Phases. SPM kräver manuell anslutning av Kotlin-ramverket via Package.swift, vilket är svårare att underhålla för stora KMM-projekt. JetBrains arbetar på SPM-stöd för Kotlin/Native, men fram till 2025 förblir SPM-integration experimentell.

Vanliga problem och lösningar

Vid användning av CocoaPods Plugin stöter KMM-utvecklare på flera vanliga problem. Versionskonflikt för pods — det vanligaste problemet, när två pods kräver olika versioner av samma beroende. Lösningen är att explicit ange versionen av det konfliktande beroendet via pod("Dependency") { version = "x.x" }. Det andra vanliga fallet — versionsinkompatibilitet, när en pod kräver en nyare iOS SDK än den lägsta versionen av KMM-projektet.

Problem med .xcworkspace uppstår om .xcodeproj öppnas istället för .xcworkspace efter konfiguration av plugin. Plugin varnar om detta i podInstall-loggarna. Ett annat vanligt fel — avsaknad av CocoaPods på utvecklarens maskin. Plugin kontrollerar förekomsten av pod-kommandot innan podInstall körs och visar ett tydligt felmeddelande. För CI/CD, installera CocoaPods: gem install cocoapods.

// Lös versionskonflikt
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Lös konflikt explicit
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

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

Felsökning av podInstall

Om podInstall avslutas med ett fel, använd flaggan --info för detaljerad utdata: ./gradlew podInstall --info. Plugin loggar varje steg: generering av Podfile, körning av pod install, tolkning av Podfile.lock. Oftast är fel relaterade till nätverksproblem (otillgänglighet av CocoaPods Trunk) eller felaktig syntax i Podfile. I sådana fall, försök att köra pod install manuellt i projektroten för att få ett mer detaljerat felmeddelande från CocoaPods.