CocoaPods Plugin — apa itu, plugin untuk KMM dan konfigurasi

Apa itu CocoaPods Plugin?

CocoaPods Plugin (juga dikenal sebagai kotlin.cocoapods) — adalah plugin resmi JetBrains untuk integrasi CocoaPods dengan Kotlin Multiplatform Mobile. Plugin ini adalah bagian dari Kotlin Gradle DSL dan dikonfigurasi langsung di build.gradle.kts modul KMM. Plugin ini mengotomatiskan pembuatan dan pemeliharaan Podfile, pembuatan .xcworkspace, dan pengelolaan dependensi pod, membebaskan pengembang dari konfigurasi manual proyek Xcode.

Sebelum munculnya CocoaPods Plugin, pengembang KMM terpaksa membuat Podfile secara manual, menjalankan pod install, mengonfigurasi bridge-header, dan melacak versi pod secara terpisah dari dependensi Gradle. Hal ini menyebabkan desinkronisasi versi dan kesulitan dalam pipeline CI/CD. Plugin memecahkan masalah ini, membuat pengelolaan dependensi iOS semudah pengelolaan dependensi Gradle di modul Android.

Plugin mendukung pod publik dari CocoaPods Trunk maupun pod kustom dari repositori pribadi. Bekerja dengan Podspec lokal dan repositori berbasis git juga didukung. Plugin kompatibel dengan Kotlin versi 1.6.0 dan lebih baru, serta memerlukan CocoaPods terinstal (gem install cocoapods) di mesin pengembang.

Bagaimana Cara Kerja CocoaPods Plugin

CocoaPods Plugin bekerja di tingkat grafik tugas Gradle, menambahkan tugas khusus untuk bekerja dengan CocoaPods. Tugas utama meliputi podInstall (instalasi pod), podGenXcodeWorkspace (pembuatan .xcworkspace), dan podBuildDebugFramework (membangun versi debug framework). Plugin menganalisis bagian cocoapods di build.gradle.kts, membuat Podfile berdasarkan dependensi yang dideklarasikan, dan menjalankan pod install dengan parameter yang diperlukan.

Arsitektur plugin mencakup tiga komponen: ekstensi DSL untuk build.gradle.kts, Podfile Generator untuk membuat Podfile, dan Lapisan Integrasi Xcode untuk mengonfigurasi .xcworkspace. Ekstensi DSL menyediakan blok cocoapods { } dengan fungsi pod() bersarang untuk mendeklarasikan dependensi, specRepo() untuk menentukan repositori pribadi, dan framework { } untuk mengonfigurasi framework keluaran. Podfile Generator menerjemahkan deklarasi ini ke dalam sintaks Ruby yang dapat dipahami oleh 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"
        }
    }
}

Siklus Hidup Tugas podInstall

Saat menjalankan podInstall, plugin secara berurutan: menghasilkan Podfile di root proyek, menjalankan pod install melalui baris perintah, menghasilkan .xcworkspace, memeriksa kesesuaian versi pod dengan yang dideklarasikan, dan menyimpan cache Podfile.lock. Saat dijalankan ulang tanpa perubahan konfigurasi, podInstall dilewati jika Podfile.lock tidak berubah. Ini menghemat waktu di CI/CD, di mana pod install dapat memakan waktu hingga 2-3 menit untuk instalasi bersih.

Konfigurasi CocoaPods Plugin di Proyek KMM

Untuk mengonfigurasi CocoaPods Plugin, perlu dilakukan beberapa langkah. Instalasi CocoaPods di mesin pengembang (gem install cocoapods) adalah syarat wajib. Kemudian di build.gradle.kts modul shared ditambahkan blok cocoapods { } dengan konfigurasi framework dan dependensi. Setelah konfigurasi, tugas podInstall harus dijalankan, yang akan membuat Podfile dan menginstal pod. .xcworkspace yang dihasilkan akan berada di root proyek di samping Podfile.

Plugin terintegrasi dengan Xcode Build Phases. Saat membangun aplikasi iOS, Xcode menjalankan embedAndSignAppleFrameworkForXcode — tugas yang menyalin framework Kotlin/Native ke bundle aplikasi. CocoaPods Plugin menambahkan fase build ini secara otomatis saat menghasilkan .xcworkspace. Jika .xcworkspace telah dihasilkan, file tersebut harus dibuka sebagai pengganti .xcodeproj untuk kompilasi yang benar dengan dependensi pod.

Contoh Kode: Konfigurasi Pod

Mari kita lihat berbagai skenario pendeklarasian pod di CocoaPods Plugin. Kasus dasar — menghubungkan pod publik dari CocoaPods Trunk dengan menentukan versi. Skenario yang lebih kompleks meliputi penggunaan podspec kustom, pod lokal, dan pod dari repositori git.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Pod publik dari CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Versi kustom dengan operator
        pod("SnapKit") { version = "~> 5.6" }

        // Pod dari repositori pribadi
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Pod lokal dengan jalur
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Menghubungkan pod hanyalah bagian dari konfigurasi. Plugin juga memungkinkan mengekspor dependensi dari modul Kotlin lain ke framework iOS. Fungsi export(project(":core")) menunjukkan bahwa semua API publik modul :core harus dapat diakses dari header Objective-C framework yang dihasilkan. Ini diperlukan ketika kode Kotlin bersama menggunakan kelas dari modul lain dan kelas tersebut harus dapat diakses dari Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // Ekspor modul ke framework iOS
        export(project(":network"))
        export(project(":domain"))

        // Koneksi statis atau dinamis
        isStatic = true
    }

    // Pod diperlukan untuk modul yang diekspor
    pod("Moya") { version = "15.0" }
}

Membangun dan Menguji

Setelah konfigurasi, podInstall harus dijalankan untuk membuat Podfile dan menginstal dependensi. Kemudian .xcworkspace yang dihasilkan dibuka di Xcode, di mana aplikasi dapat dibangun dengan cara standar. Untuk CI/CD, pastikan CocoaPods dan Ruby terinstal di mesin build. Plugin mendukung bendera --no-daemon untuk bekerja di lingkungan CI.

// Instalasi pod menghasilkan Podfile + xcworkspace
./gradlew :shared:podInstall

// Bangun framework debug untuk pengujian
./gradlew :shared:podBuildDebugFramework

// Build iOS lengkap dari baris perintah
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — manajer dependensi alternatif dari Apple, yang semakin populer dan secara bertahap menggantikan CocoaPods di komunitas iOS. Namun CocoaPods Plugin tetap relevan karena beberapa alasan: SPM tidak mendukung framework dinamis dalam konteks KMM, dan integrasi framework Kotlin/Native melalui SPM memerlukan konfigurasi tambahan. CocoaPods Plugin menyediakan jalur integrasi yang lebih matang dan terdokumentasi.

Perbandingan CocoaPods Plugin dan integrasi langsung melalui SPM menunjukkan bahwa yang pertama unggul dalam otomatisasi, dan yang kedua dalam dukungan native Apple. CocoaPods Plugin secara otomatis menghasilkan Podfile, mengelola versi, dan mengonfigurasi Xcode Build Phases. SPM memerlukan koneksi manual framework Kotlin melalui Package.swift, yang lebih sulit dipelihara untuk proyek KMM besar. JetBrains sedang mengerjakan dukungan SPM untuk Kotlin/Native, tetapi hingga tahun 2025 integrasi SPM tetap eksperimental.

Masalah Umum dan Solusi

Saat menggunakan CocoaPods Plugin, pengembang KMM menghadapi beberapa masalah umum. Konflik versi pod — masalah paling umum, ketika dua pod memerlukan versi berbeda dari dependensi yang sama. Solusinya adalah menentukan secara eksplisit versi dependensi yang berkonflik melalui pod("Dependency") { version = "x.x" }. Kasus umum kedua — ketidakcocokan versi, ketika pod memerlukan iOS SDK yang lebih baru dari versi minimum proyek KMM.

Masalah dengan .xcworkspace muncul jika .xcodeproj dibuka sebagai pengganti .xcworkspace setelah konfigurasi plugin. Plugin memperingatkan tentang hal ini di log podInstall. Kesalahan umum lainnya — tidak adanya CocoaPods di mesin pengembang. Plugin memeriksa keberadaan perintah pod sebelum menjalankan podInstall dan menampilkan pesan kesalahan yang jelas. Untuk CI/CD, instal CocoaPods: gem install cocoapods.

// Selesaikan konflik versi
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Selesaikan konflik secara eksplisit
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Periksa instalasi CocoaPods melalui Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Versi CocoaPods: $result")
    }
}

Debug podInstall

Jika podInstall berakhir dengan kesalahan, gunakan bendera --info untuk keluaran terperinci: ./gradlew podInstall --info. Plugin mencatat setiap langkah: pembuatan Podfile, menjalankan pod install, penguraian Podfile.lock. Paling sering, kesalahan terkait dengan masalah jaringan (ketidaktersediaan CocoaPods Trunk) atau sintaks Podfile yang salah. Dalam kasus seperti itu, coba jalankan pod install secara manual di root proyek untuk mendapatkan pesan kesalahan yang lebih terperinci dari CocoaPods.