CocoaPods Plugin — ce que c'est, un plugin pour KMM et configuration

Qu'est-ce que CocoaPods Plugin ?

CocoaPods Plugin (également connu sous le nom de kotlin.cocoapods) est un plugin officiel de JetBrains pour intégrer CocoaPods avec Kotlin Multiplatform Mobile. Le plugin fait partie de Kotlin Gradle DSL et se configure directement dans build.gradle.kts du module KMM. Il automatise la création et la maintenance du Podfile, la génération de .xcworkspace et la gestion des dépendances de pods, éliminant le besoin de configuration manuelle du projet Xcode.

Avant CocoaPods Plugin, les développeurs KMM étaient obligés de créer manuellement un Podfile, d'exécuter pod install, de configurer les bridge headers et de suivre les versions des pods séparément des dépendances Gradle. Cela entraînait une désynchronisation des versions et des difficultés dans les pipelines CI/CD. Le plugin a résolu ces problèmes en rendant la gestion des dépendances iOS aussi simple que la gestion des dépendances Gradle dans les modules Android.

Le plugin prend en charge à la fois les pods publics de CocoaPods Trunk et les pods personnalisés provenant de dépôts privés. Le travail avec des Podspec locales et des dépôts basés sur git est également pris en charge. Le plugin est compatible avec Kotlin 1.6.0 et supérieur, et nécessite que CocoaPods (gem install cocoapods) soit installé sur la machine de développement.

Comment fonctionne CocoaPods Plugin

CocoaPods Plugin opère au niveau du task-graph de Gradle, ajoutant des tâches spécialisées pour travailler avec CocoaPods. Les principales tâches incluent podInstall (installation des pods), podGenXcodeWorkspace (génération de .xcworkspace) et podBuildDebugFramework (construction de la version Debug du framework). Le plugin analyse la section cocoapods dans build.gradle.kts, crée un Podfile basé sur les dépendances déclarées et exécute pod install avec les paramètres nécessaires.

L'architecture du plugin comprend trois composants : une extension DSL pour build.gradle.kts, un Générateur de Podfile pour créer le Podfile et une Couche d'intégration Xcode pour configurer .xcworkspace. L'extension DSL fournit un bloc cocoapods { } avec des fonctions imbriquées pod() pour déclarer les dépendances, specRepo() pour spécifier les dépôts privés et framework { } pour configurer le framework de sortie. Le Générateur de Podfile traduit ces déclarations en syntaxe Ruby compréhensible par 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"
        }
    }
}

Cycle de vie de la tâche podInstall

Lors de l'exécution de podInstall, le plugin séquentiellement : génère un Podfile à la racine du projet, exécute pod install via la ligne de commande, génère .xcworkspace, vérifie que les versions des pods correspondent aux versions déclarées et met en cache Podfile.lock. Lors des exécutions ultérieures sans changement de configuration, podInstall est ignoré si Podfile.lock n'a pas changé. Cela permet d'économiser du temps en CI/CD, où pod install peut prendre jusqu'à 2-3 minutes pour une installation propre.

Configuration de CocoaPods Plugin dans un projet KMM

La configuration de CocoaPods Plugin nécessite plusieurs étapes. L'installation de CocoaPods sur la machine de développement (gem install cocoapods) est un prérequis. Ensuite, dans build.gradle.kts du module shared, ajoutez un bloc cocoapods { } avec la configuration du framework et les dépendances. Après la configuration, exécutez la tâche podInstall, qui créera le Podfile et installera les pods. Le .xcworkspace généré sera situé à la racine du projet à côté du Podfile.

Le plugin s'intègre avec Xcode Build Phases. Lors de la compilation d'une application iOS, Xcode exécute embedAndSignAppleFrameworkForXcode — une tâche qui copie le framework Kotlin/Native dans le bundle de l'application. CocoaPods Plugin ajoute cette phase de build automatiquement lors de la génération de .xcworkspace. Si .xcworkspace a été généré, il doit être ouvert à la place de .xcodeproj pour des compilations correctes avec les dépendances de pods.

Exemples de code : configuration des pods

Examinons différents scénarios de déclaration de pods dans CocoaPods Plugin. Le cas de base consiste à connecter un pod public de CocoaPods Trunk avec une version spécifiée. Les scénarios plus complexes incluent l'utilisation de podspec personnalisés, de pods locaux et de pods provenant de dépôts git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

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

        // Version personnalisée avec opérateur
        pod("SnapKit") { version = "~> 5.6" }

        // Pod de dépôt privé
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

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

        // Pod de dépôt git
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

Connecter des pods n'est qu'une partie de la configuration. Le plugin permet également d'exporter des dépendances d'autres modules Kotlin vers le framework iOS. La fonction export(project(":core")) spécifie que toutes les API publiques du module :core doivent être accessibles depuis l'en-tête Objective-C du framework généré. Cela est nécessaire lorsque le code Kotlin partagé utilise des classes d'un autre module et qu'elles doivent être accessibles depuis Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Exporter les modules vers le framework iOS
        export(project(":network"))
        export(project(":domain"))

        // Liaison statique ou dynamique
        isStatic = true
    }

    // Pod requis pour les modules exportés
    pod("Moya") { version = "15.0" }
}

Compilation et tests

Après la configuration, vous devez exécuter podInstall pour générer le Podfile et installer les dépendances. Ensuite, le .xcworkspace généré est ouvert dans Xcode, où l'application peut être compilée de manière standard. Pour le CI/CD, assurez-vous que CocoaPods et Ruby sont installés sur la machine de build. Le plugin prend en charge le flag --no-daemon pour fonctionner dans un environnement CI.

// Installer les pods génère Podfile + xcworkspace
./gradlew :shared:podInstall

// Compiler le framework debug pour les tests
./gradlew :shared:podBuildDebugFramework

// Build iOS complet depuis la ligne de commande
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) est un gestionnaire de dépendances alternatif d'Apple qui gagne en popularité et remplace progressivement CocoaPods dans la communauté iOS. Cependant, CocoaPods Plugin reste pertinent pour plusieurs raisons : SPM ne prend pas en charge les frameworks dynamiques dans le contexte KMM, et l'intégration du framework Kotlin/Native via SPM nécessite une configuration supplémentaire. CocoaPods Plugin fournit un chemin d'intégration plus mature et documenté.

La comparaison de CocoaPods Plugin et de l'intégration directe via SPM montre que le premier gagne en automatisation, tandis que le second gagne en support natif Apple. CocoaPods Plugin génère automatiquement un Podfile, gère les versions et configure les Xcode Build Phases. SPM nécessite de connecter manuellement le framework Kotlin via Package.swift, ce qui est plus difficile à maintenir pour les grands projets KMM. JetBrains travaille sur le support SPM pour Kotlin/Native, mais en 2025, l'intégration SPM reste expérimentale.

Problèmes courants et solutions

Lors de l'utilisation de CocoaPods Plugin, les développeurs KMM rencontrent plusieurs problèmes typiques. Le conflit de versions de pods est le problème le plus courant, lorsque deux pods nécessitent des versions différentes d'une même dépendance. La solution consiste à spécifier explicitement la version de la dépendance conflictuelle via pod("Dependency") { version = "x.x" }. Le deuxième cas courant est l'incompatibilité de version, lorsqu'un pod nécessite un SDK iOS plus récent que la version minimale du projet KMM.

Les problèmes avec .xcworkspace surviennent si vous ouvrez .xcodeproj au lieu de .xcworkspace après la configuration du plugin. Le plugin vous avertit dans les logs de podInstall. Une autre erreur fréquente est l'absence de CocoaPods sur la machine de développement. Le plugin vérifie la présence de la commande pod avant d'exécuter podInstall et affiche un message d'erreur clair. Pour le CI/CD, installez CocoaPods : gem install cocoapods.

// Résoudre le conflit de version
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Résoudre explicitement le conflit
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Vérifier l'installation de CocoaPods via Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Version de CocoaPods : $result")
    }
}

Débogage de podInstall

Si podInstall échoue, utilisez le flag --info pour une sortie détaillée : ./gradlew podInstall --info. Le plugin enregistre chaque étape : génération du Podfile, exécution de pod install, analyse de Podfile.lock. La plupart du temps, les erreurs sont liées à des problèmes réseau (CocoaPods Trunk indisponible) ou à une syntaxe incorrecte du Podfile. Dans de tels cas, essayez d'exécuter pod install manuellement à la racine du projet pour obtenir un message d'erreur plus détaillé de CocoaPods.