CocoaPods Plugin — qué es, un plugin para KMM y configuración

¿Qué es CocoaPods Plugin?

CocoaPods Plugin (también conocido como kotlin.cocoapods) es un plugin oficial de JetBrains para integrar CocoaPods con Kotlin Multiplatform Mobile. El plugin forma parte de Kotlin Gradle DSL y se configura directamente en build.gradle.kts del módulo KMM. Automatiza la creación y el mantenimiento del Podfile, la generación de .xcworkspace y la gestión de dependencias de pods, eliminando la necesidad de configuración manual del proyecto Xcode.

Antes de CocoaPods Plugin, los desarrolladores de KMM tenían que crear manualmente un Podfile, ejecutar pod install, configurar bridge headers y hacer seguimiento de las versiones de pods por separado de las dependencias de Gradle. Esto provocaba desincronización de versiones y dificultades en los pipelines de CI/CD. El plugin resolvió estos problemas haciendo que la gestión de dependencias de iOS sea tan sencilla como gestionar dependencias de Gradle en módulos Android.

El plugin admite tanto pods públicos de CocoaPods Trunk como pods personalizados de repositorios privados. También se admite el trabajo con Podspec locales y repositorios basados en git. El plugin es compatible con Kotlin 1.6.0 y superior, y requiere tener CocoaPods instalado (gem install cocoapods) en la máquina de desarrollo.

Cómo funciona CocoaPods Plugin

CocoaPods Plugin opera a nivel del task-graph de Gradle, añadiendo tareas especializadas para trabajar con CocoaPods. Las tareas principales incluyen podInstall (instalación de pods), podGenXcodeWorkspace (generación de .xcworkspace) y podBuildDebugFramework (compilación de la versión Debug del framework). El plugin analiza la sección cocoapods en build.gradle.kts, crea un Podfile basado en las dependencias declaradas y ejecuta pod install con los parámetros necesarios.

La arquitectura del plugin incluye tres componentes: una extensión DSL para build.gradle.kts, un Generador de Podfile para crear el Podfile y una Capa de Integración con Xcode para configurar .xcworkspace. La extensión DSL proporciona un bloque cocoapods { } con funciones anidadas pod() para declarar dependencias, specRepo() para especificar repositorios privados y framework { } para configurar el framework de salida. El Generador de Podfile traduce estas declaraciones a sintaxis Ruby comprensible para 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 de vida de la tarea podInstall

Al ejecutar podInstall, el plugin secuencialmente: genera un Podfile en la raíz del proyecto, ejecuta pod install mediante línea de comandos, genera .xcworkspace, verifica que las versiones de los pods coincidan con las declaradas y almacena en caché Podfile.lock. En ejecuciones posteriores sin cambios en la configuración, podInstall se omite si Podfile.lock no ha cambiado. Esto ahorra tiempo en CI/CD, donde pod install puede tardar hasta 2-3 minutos en una instalación limpia.

Configuración de CocoaPods Plugin en un proyecto KMM

La configuración de CocoaPods Plugin requiere varios pasos. Instalar CocoaPods en la máquina de desarrollo (gem install cocoapods) es un requisito previo. Luego, en build.gradle.kts del módulo shared, se añade un bloque cocoapods { } con la configuración del framework y las dependencias. Después de la configuración, se ejecuta la tarea podInstall, que creará el Podfile e instalará los pods. El .xcworkspace generado se ubicará en la raíz del proyecto junto al Podfile.

El plugin se integra con Xcode Build Phases. Al compilar una aplicación iOS, Xcode ejecuta embedAndSignAppleFrameworkForXcode, una tarea que copia el framework Kotlin/Native en el bundle de la aplicación. CocoaPods Plugin añade esta build phase automáticamente al generar .xcworkspace. Si se generó .xcworkspace, debe abrirse en lugar de .xcodeproj para compilaciones correctas con dependencias de pods.

Ejemplos de código: configuración de pods

Veamos varios escenarios para declarar pods en CocoaPods Plugin. El caso básico es conectar un pod público de CocoaPods Trunk con una versión especificada. Los escenarios más complejos incluyen el uso de podspec personalizados, pods locales y pods de repositorios git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Pod público de CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Versión personalizada con operador
        pod("SnapKit") { version = "~> 5.6" }

        // Pod de repositorio privado
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

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

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

Conectar pods es solo parte de la configuración. El plugin también permite exportar dependencias de otros módulos Kotlin al framework de iOS. La función export(project(":core")) especifica que todas las API públicas del módulo :core deben ser accesibles desde el encabezado Objective-C del framework generado. Esto es necesario cuando el código Kotlin compartido usa clases de otro módulo y deben ser accesibles desde Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Exportar módulos al framework de iOS
        export(project(":network"))
        export(project(":domain"))

        // Enlace estático o dinámico
        isStatic = true
    }

    // Pod requerido para módulos exportados
    pod("Moya") { version = "15.0" }
}

Compilación y pruebas

Después de la configuración, es necesario ejecutar podInstall para generar el Podfile e instalar las dependencias. Luego, el .xcworkspace generado se abre en Xcode, donde se puede compilar la aplicación de forma estándar. Para CI/CD, asegúrese de que CocoaPods y Ruby estén instalados en la máquina de compilación. El plugin admite la bandera --no-daemon para trabajar en entornos CI.

// Instalar pods genera Podfile + xcworkspace
./gradlew :shared:podInstall

// Compilar framework debug para pruebas
./gradlew :shared:podBuildDebugFramework

// Compilación completa de iOS desde línea de comandos
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) es un gestor de dependencias alternativo de Apple que está ganando popularidad y reemplazando gradualmente a CocoaPods en la comunidad iOS. Sin embargo, CocoaPods Plugin sigue siendo relevante por varias razones: SPM no admite frameworks dinámicos en el contexto KMM, y la integración del framework Kotlin/Native a través de SPM requiere configuración adicional. CocoaPods Plugin proporciona un camino de integración más maduro y documentado.

Comparación de CocoaPods Plugin y la integración directa con SPM muestra que el primero gana en automatización, mientras que el segundo gana en soporte nativo de Apple. CocoaPods Plugin genera automáticamente un Podfile, gestiona versiones y configura Xcode Build Phases. SPM requiere conectar manualmente el framework Kotlin a través de Package.swift, lo que es más difícil de mantener para proyectos KMM grandes. JetBrains está trabajando en soporte SPM para Kotlin/Native, pero en 2025 la integración con SPM sigue siendo experimental.

Problemas comunes y soluciones

Al usar CocoaPods Plugin, los desarrolladores KMM se encuentran con varios problemas típicos. Conflicto de versiones de pods es el problema más común, cuando dos pods requieren versiones diferentes de la misma dependencia. La solución es especificar explícitamente la versión de la dependencia conflictiva mediante pod("Dependency") { version = "x.x" }. El segundo caso común es la incompatibilidad de versiones, cuando un pod requiere un SDK de iOS más nuevo que la versión mínima del proyecto KMM.

Problemas con .xcworkspace surgen si se abre .xcodeproj en lugar de .xcworkspace después de configurar el plugin. El plugin advierte sobre esto en los registros de podInstall. Otro error frecuente es la ausencia de CocoaPods en la máquina de desarrollo. El plugin verifica la presencia del comando pod antes de ejecutar podInstall y muestra un mensaje de error claro. Para CI/CD, instale CocoaPods: gem install cocoapods.

// Resolver conflicto de versión
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Resolver conflicto explícitamente
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Verificar instalación de CocoaPods mediante Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Versión de CocoaPods: $result")
    }
}

Depuración de podInstall

Si podInstall falla, use la bandera --info para obtener una salida detallada: ./gradlew podInstall --info. El plugin registra cada paso: generación del Podfile, ejecución de pod install, análisis de Podfile.lock. La mayoría de las veces, los errores están relacionados con problemas de red (CocoaPods Trunk no disponible) o sintaxis incorrecta del Podfile. En tales casos, intente ejecutar pod install manualmente en la raíz del proyecto para obtener un mensaje de error más detallado de CocoaPods.