CocoaPods Plugin — cos'è, un plugin per KMM e configurazione

Cos'è CocoaPods Plugin?

CocoaPods Plugin (noto anche come kotlin.cocoapods) è un plugin ufficiale di JetBrains per integrare CocoaPods con Kotlin Multiplatform Mobile. Il plugin fa parte del Kotlin Gradle DSL e viene configurato direttamente in build.gradle.kts del modulo KMM. Automatizza la creazione e la manutenzione del Podfile, la generazione di .xcworkspace e la gestione delle dipendenze dei pod, eliminando la necessità di configurazione manuale del progetto Xcode.

Prima di CocoaPods Plugin, gli sviluppatori KMM erano costretti a creare manualmente un Podfile, eseguire pod install, configurare bridge header e tenere traccia delle versioni dei pod separatamente dalle dipendenze Gradle. Ciò portava a desincronizzazione delle versioni e difficoltà nelle pipeline CI/CD. Il plugin ha risolto questi problemi rendendo la gestione delle dipendenze iOS semplice come la gestione delle dipendenze Gradle nei moduli Android.

Il plugin supporta sia pod pubblici da CocoaPods Trunk che pod personalizzati da repository privati. Anche il lavoro con Podspec locali e repository basati su git è supportato. Il plugin è compatibile con Kotlin 1.6.0 e superiori e richiede CocoaPods installato (gem install cocoapods) sulla macchina di sviluppo.

Come funziona CocoaPods Plugin

CocoaPods Plugin opera a livello di task-graph di Gradle, aggiungendo attività specializzate per lavorare con CocoaPods. Le attività principali includono podInstall (installazione dei pod), podGenXcodeWorkspace (generazione di .xcworkspace) e podBuildDebugFramework (costruzione della versione Debug del framework). Il plugin analizza la sezione cocoapods in build.gradle.kts, crea un Podfile basato sulle dipendenze dichiarate ed esegue pod install con i parametri necessari.

L'architettura del plugin comprende tre componenti: un'estensione DSL per build.gradle.kts, un Generatore di Podfile per creare il Podfile e un Livello di Integrazione Xcode per configurare .xcworkspace. L'estensione DSL fornisce un blocco cocoapods { } con funzioni nidificate pod() per dichiarare dipendenze, specRepo() per specificare repository privati e framework { } per configurare il framework di output. Il Generatore di Podfile traduce queste dichiarazioni nella sintassi Ruby comprensibile da 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"
        }
    }
}

Ciclo di vita dell'attività podInstall

Durante l'esecuzione di podInstall, il plugin sequenzialmente: genera un Podfile nella radice del progetto, esegue pod install tramite riga di comando, genera .xcworkspace, verifica che le versioni dei pod corrispondano a quelle dichiarate e memorizza nella cache Podfile.lock. Nelle esecuzioni successive senza modifiche alla configurazione, podInstall viene saltato se Podfile.lock non è cambiato. Questo risparmia tempo in CI/CD, dove pod install può richiedere fino a 2-3 minuti per un'installazione pulita.

Configurazione di CocoaPods Plugin in un progetto KMM

La configurazione di CocoaPods Plugin richiede diversi passaggi. Installare CocoaPods sulla macchina di sviluppo (gem install cocoapods) è un prerequisito. Quindi, in build.gradle.kts del modulo condiviso, aggiungere un blocco cocoapods { } con la configurazione del framework e le dipendenze. Dopo la configurazione, eseguire l'attività podInstall, che creerà il Podfile e installerà i pod. Il .xcworkspace generato si troverà nella radice del progetto accanto al Podfile.

Il plugin si integra con Xcode Build Phases. Durante la compilazione di un'app iOS, Xcode esegue embedAndSignAppleFrameworkForXcode — un'attività che copia il framework Kotlin/Native nel bundle dell'app. CocoaPods Plugin aggiunge automaticamente questa build phase durante la generazione di .xcworkspace. Se .xcworkspace è stato generato, deve essere aperto invece di .xcodeproj per compilazioni corrette con dipendenze dei pod.

Esempi di codice: configurazione dei pod

Esaminiamo vari scenari per dichiarare i pod in CocoaPods Plugin. Il caso base è collegare un pod pubblico da CocoaPods Trunk con una versione specificata. Scenari più complessi includono l'uso di podspec personalizzati, pod locali e pod da repository git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Pod pubblico da CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Versione personalizzata con operatore
        pod("SnapKit") { version = "~> 5.6" }

        // Pod da repository privato
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Pod locale con percorso
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Collegare i pod è solo una parte della configurazione. Il plugin consente anche di esportare dipendenze da altri moduli Kotlin al framework iOS. La funzione export(project(":core")) specifica che tutte le API pubbliche del modulo :core devono essere accessibili dall'intestazione Objective-C del framework generato. Ciò è necessario quando il codice Kotlin condiviso utilizza classi da un altro modulo e devono essere accessibili da Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Esporta moduli nel framework iOS
        export(project(":network"))
        export(project(":domain"))

        // Link statico o dinamico
        isStatic = true
    }

    // Pod richiesto per i moduli esportati
    pod("Moya") { version = "15.0" }
}

Compilazione e test

Dopo la configurazione, è necessario eseguire podInstall per generare il Podfile e installare le dipendenze. Quindi il .xcworkspace generato viene aperto in Xcode, dove l'app può essere compilata in modo standard. Per CI/CD, assicurarsi che CocoaPods e Ruby siano installati sulla macchina di build. Il plugin supporta il flag --no-daemon per funzionare in ambiente CI.

// Installare pod genera Podfile + xcworkspace
./gradlew :shared:podInstall

// Compilare framework debug per test
./gradlew :shared:podBuildDebugFramework

// Build iOS completo da riga di comando
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) è un gestore di dipendenze alternativo di Apple che sta guadagnando popolarità e sostituendo gradualmente CocoaPods nella comunità iOS. Tuttavia, CocoaPods Plugin rimane rilevante per diversi motivi: SPM non supporta framework dinamici nel contesto KMM e l'integrazione del framework Kotlin/Native tramite SPM richiede configurazione aggiuntiva. CocoaPods Plugin fornisce un percorso di integrazione più maturo e documentato.

Il confronto tra CocoaPods Plugin e l'integrazione diretta tramite SPM mostra che il primo vince in automazione, mentre il secondo vince nel supporto nativo Apple. CocoaPods Plugin genera automaticamente un Podfile, gestisce le versioni e configura le Xcode Build Phases. SPM richiede il collegamento manuale del framework Kotlin tramite Package.swift, il che è più difficile da mantenere per progetti KMM di grandi dimensioni. JetBrains sta lavorando al supporto SPM per Kotlin/Native, ma al 2025 l'integrazione SPM rimane sperimentale.

Problemi comuni e soluzioni

Utilizzando CocoaPods Plugin, gli sviluppatori KMM incontrano diversi problemi tipici. Conflitto di versioni dei pod è il problema più comune, quando due pod richiedono versioni diverse della stessa dipendenza. La soluzione è specificare esplicitamente la versione della dipendenza in conflitto tramite pod("Dependency") { version = "x.x" }. Il secondo caso comune è l'incompatibilità di versione, quando un pod richiede un SDK iOS più recente della versione minima del progetto KMM.

Problemi con .xcworkspace sorgono se si apre .xcodeproj invece di .xcworkspace dopo aver configurato il plugin. Il plugin avvisa di questo nei log di podInstall. Un altro errore frequente è l'assenza di CocoaPods sulla macchina di sviluppo. Il plugin verifica la presenza del comando pod prima di eseguire podInstall e mostra un messaggio di errore chiaro. Per CI/CD, installare CocoaPods: gem install cocoapods.

// Risolvi conflitto di versione
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Risolvi conflitto esplicitamente
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Controlla installazione CocoaPods tramite Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Versione CocoaPods: $result")
    }
}

Debug di podInstall

Se podInstall fallisce, utilizzare il flag --info per un output dettagliato: ./gradlew podInstall --info. Il plugin registra ogni passo: generazione del Podfile, esecuzione di pod install, analisi di Podfile.lock. Spesso gli errori sono correlati a problemi di rete (CocoaPods Trunk non disponibile) o sintassi errata del Podfile. In tali casi, provare a eseguire pod install manualmente nella radice del progetto per ottenere un messaggio di errore più dettagliato da CocoaPods.