CocoaPods Plugin — o que é, um plugin para KMM e configuração

O que é CocoaPods Plugin?

CocoaPods Plugin (também conhecido como kotlin.cocoapods) é um plugin oficial da JetBrains para integrar CocoaPods com Kotlin Multiplatform Mobile. O plugin faz parte do Kotlin Gradle DSL e é configurado diretamente no build.gradle.kts do módulo KMM. Ele automatiza a criação e manutenção do Podfile, geração do .xcworkspace e gerenciamento de dependências de pods, eliminando a necessidade de configuração manual do projeto Xcode.

Antes do CocoaPods Plugin, os desenvolvedores KMM eram forçados a criar manualmente um Podfile, executar pod install, configurar bridge headers e rastrear versões de pods separadamente das dependências Gradle. Isso levava à dessincronização de versões e dificuldades em pipelines CI/CD. O plugin resolveu esses problemas tornando o gerenciamento de dependências iOS tão simples quanto gerenciar dependências Gradle em módulos Android.

O plugin suporta tanto pods públicos do CocoaPods Trunk quanto pods personalizados de repositórios privados. O trabalho com Podspec locais e repositórios baseados em git também é suportado. O plugin é compatível com Kotlin 1.6.0 e superior, e requer CocoaPods instalado (gem install cocoapods) na máquina de desenvolvimento.

Como funciona o CocoaPods Plugin

CocoaPods Plugin opera no nível do task-graph do Gradle, adicionando tarefas especializadas para trabalhar com CocoaPods. As principais tarefas incluem podInstall (instalação de pods), podGenXcodeWorkspace (geração de .xcworkspace) e podBuildDebugFramework (construção da versão Debug do framework). O plugin analisa a seção cocoapods no build.gradle.kts, cria um Podfile com base nas dependências declaradas e executa pod install com os parâmetros necessários.

A arquitetura do plugin inclui três componentes: uma extensão DSL para build.gradle.kts, um Gerador de Podfile para criar o Podfile e uma Camada de Integração Xcode para configurar .xcworkspace. A extensão DSL fornece um bloco cocoapods { } com funções aninhadas pod() para declarar dependências, specRepo() para especificar repositórios privados e framework { } para configurar o framework de saída. O Gerador de Podfile traduz essas declarações para sintaxe Ruby compreensível pelo 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 da tarefa podInstall

Ao executar podInstall, o plugin sequencialmente: gera um Podfile na raiz do projeto, executa pod install via linha de comando, gera .xcworkspace, verifica se as versões dos pods correspondem às declaradas e armazena em cache Podfile.lock. Em execuções subsequentes sem alterações de configuração, podInstall é ignorado se Podfile.lock não mudou. Isso economiza tempo em CI/CD, onde pod install pode levar até 2-3 minutos para uma instalação limpa.

Configuração do CocoaPods Plugin em um projeto KMM

A configuração do CocoaPods Plugin requer várias etapas. Instalar CocoaPods na máquina de desenvolvimento (gem install cocoapods) é um pré-requisito. Em seguida, no build.gradle.kts do módulo shared, adicione um bloco cocoapods { } com a configuração do framework e dependências. Após a configuração, execute a tarefa podInstall, que criará o Podfile e instalará os pods. O .xcworkspace gerado estará localizado na raiz do projeto ao lado do Podfile.

O plugin se integra com Xcode Build Phases. Ao compilar um aplicativo iOS, o Xcode executa embedAndSignAppleFrameworkForXcode — uma tarefa que copia o framework Kotlin/Native para o bundle do aplicativo. O CocoaPods Plugin adiciona esta build phase automaticamente ao gerar .xcworkspace. Se .xcworkspace foi gerado, ele deve ser aberto em vez de .xcodeproj para compilações corretas com dependências de pods.

Exemplos de código: configuração de pods

Vamos examinar vários cenários para declarar pods no CocoaPods Plugin. O caso básico é conectar um pod público do CocoaPods Trunk com uma versão especificada. Cenários mais complexos incluem o uso de podspec personalizados, pods locais e pods de repositórios git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

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

        // Versão personalizada com operador
        pod("SnapKit") { version = "~> 5.6" }

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

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

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

Conectar pods é apenas parte da configuração. O plugin também permite exportar dependências de outros módulos Kotlin para o framework iOS. A função export(project(":core")) especifica que todas as APIs públicas do módulo :core devem estar acessíveis a partir do cabeçalho Objective-C do framework gerado. Isso é necessário quando o código Kotlin compartilhado usa classes de outro módulo e elas precisam estar acessíveis a partir do Swift.

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

        // Linkagem estática ou dinâmica
        isStatic = true
    }

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

Compilação e testes

Após a configuração, é necessário executar podInstall para gerar o Podfile e instalar as dependências. Em seguida, o .xcworkspace gerado é aberto no Xcode, onde o aplicativo pode ser compilado da forma padrão. Para CI/CD, certifique-se de que CocoaPods e Ruby estão instalados na máquina de compilação. O plugin suporta a flag --no-daemon para funcionar em ambientes CI.

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

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

// Compilação iOS completa pela linha de comando
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) é um gerenciador de dependências alternativo da Apple que está ganhando popularidade e gradualmente substituindo CocoaPods na comunidade iOS. No entanto, o CocoaPods Plugin permanece relevante por várias razões: SPM não suporta frameworks dinâmicos no contexto KMM, e a integração do framework Kotlin/Native através do SPM requer configuração adicional. O CocoaPods Plugin fornece um caminho de integração mais maduro e documentado.

Comparação do CocoaPods Plugin e da integração direta com SPM mostra que o primeiro vence em automação, enquanto o segundo vence em suporte nativo da Apple. O CocoaPods Plugin gera automaticamente um Podfile, gerencia versões e configura Xcode Build Phases. O SPM requer conectar manualmente o framework Kotlin através do Package.swift, o que é mais difícil de manter para grandes projetos KMM. A JetBrains está trabalhando no suporte SPM para Kotlin/Native, mas em 2025 a integração SPM permanece experimental.

Problemas comuns e soluções

Ao usar o CocoaPods Plugin, os desenvolvedores KMM encontram vários problemas típicos. Conflito de versões de pods é o problema mais comum, quando dois pods exigem versões diferentes da mesma dependência. A solução é especificar explicitamente a versão da dependência conflitante através de pod("Dependency") { version = "x.x" }. O segundo caso comum é incompatibilidade de versão, quando um pod requer um SDK iOS mais novo que a versão mínima do projeto KMM.

Problemas com .xcworkspace surgem se você abrir .xcodeproj em vez de .xcworkspace após configurar o plugin. O plugin avisa sobre isso nos logs do podInstall. Outro erro frequente é a ausência do CocoaPods na máquina de desenvolvimento. O plugin verifica a presença do comando pod antes de executar podInstall e exibe uma mensagem de erro clara. Para CI/CD, instale CocoaPods: gem install cocoapods.

// Resolver conflito de versão
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Resolver conflito explicitamente
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Verificar instalação do CocoaPods via Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Versão do CocoaPods: $result")
    }
}

Depuração do podInstall

Se podInstall falhar, use a flag --info para saída detalhada: ./gradlew podInstall --info. O plugin registra cada etapa: geração do Podfile, execução do pod install, análise do Podfile.lock. Na maioria das vezes, os erros estão relacionados a problemas de rede (CocoaPods Trunk indisponível) ou sintaxe incorreta do Podfile. Nesses casos, tente executar pod install manualmente na raiz do projeto para obter uma mensagem de erro mais detalhada do CocoaPods.