CocoaPods Plugin — nedir, KMM için eklenti ve kurulum

CocoaPods Plugin nedir?

CocoaPods Plugin (kotlin.cocoapods olarak da bilinir), CocoaPods'u Kotlin Multiplatform Mobile ile entegre etmek için JetBrains'in resmi eklentisidir. Eklenti, Kotlin Gradle DSL'in bir parçasıdır ve doğrudan KMM modülünün build.gradle.kts dosyasında yapılandırılır. Podfile oluşturma ve bakımını, .xcworkspace oluşturmayı ve pod bağımlılıklarını yönetmeyi otomatikleştirerek manuel Xcode proje yapılandırması ihtiyacını ortadan kaldırır.

CocoaPods Plugin'den önce, KMM geliştiricileri manuel olarak Podfile oluşturmak, pod install çalıştırmak, bridge header'ları yapılandırmak ve pod sürümlerini Gradle bağımlılıklarından ayrı olarak takip etmek zorundaydı. Bu, sürüm senkronizasyon bozukluğuna ve CI/CD pipeline'larında zorluklara yol açıyordu. Eklenti, iOS bağımlılık yönetimini Android modüllerindeki Gradle bağımlılıklarını yönetmek kadar basit hale getirerek bu sorunları çözdü.

Eklenti, CocoaPods Trunk'tan genel podları ve özel depolardan özel podları destekler. Yerel Podspec ve git tabanlı depolarla çalışma da desteklenir. Eklenti, Kotlin 1.6.0 ve üzeri ile uyumludur ve geliştirme makinesinde CocoaPods (gem install cocoapods) yüklü olmasını gerektirir.

CocoaPods Plugin nasıl çalışır

CocoaPods Plugin, Gradle görev grafiği seviyesinde çalışır ve CocoaPods ile çalışmak için özelleşmiş görevler ekler. Ana görevler arasında podInstall (podları yükleme), podGenXcodeWorkspace (.xcworkspace oluşturma) ve podBuildDebugFramework (framework'ün Debug sürümünü derleme) bulunur. Eklenti, build.gradle.kts içindeki cocoapods bölümünü analiz eder, bildirilen bağımlılıklara dayalı bir Podfile oluşturur ve gerekli parametrelerle pod install çalıştırır.

Eklenti mimarisi üç bileşen içerir: build.gradle.kts için bir DSL uzantısı, Podfile oluşturmak için bir Podfile Oluşturucu ve .xcworkspace'i yapılandırmak için bir Xcode Entegrasyon Katmanı. DSL uzantısı, bağımlılıkları bildirmek için iç içe pod() işlevleri, özel depoları belirtmek için specRepo() ve çıktı framework'ünü yapılandırmak için framework { } ile birlikte bir cocoapods { } bloğu sağlar. Podfile Oluşturucu, bu bildirimleri CocoaPods tarafından anlaşılan Ruby sözdizimine çevirir.

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"
        }
    }
}

podInstall görevinin yaşam döngüsü

podInstall yürütülürken, eklenti sırasıyla: proje kökünde bir Podfile oluşturur, komut satırı üzerinden pod install çalıştırır, .xcworkspace oluşturur, pod sürümlerinin bildirilenlerle eşleştiğini kontrol eder ve Podfile.lock'u önbelleğe alır. Yapılandırma değişikliği olmadan sonraki çalıştırmalarda, Podfile.lock değişmediyse podInstall atlanır. Bu, temiz bir kurulumda pod install'ın 2-3 dakika sürebileceği CI/CD'de zaman tasarrufu sağlar.

KMM projesinde CocoaPods Plugin kurulumu

CocoaPods Plugin kurulumu birkaç adım gerektirir. Geliştirme makinesinde CocoaPods yüklenmesi (gem install cocoapods) bir ön koşuldur. Ardından, paylaşılan modülün build.gradle.kts dosyasına, framework yapılandırması ve bağımlılıkları ile birlikte bir cocoapods { } bloğu eklenir. Yapılandırmadan sonra, Podfile'ı oluşturacak ve podları yükleyecek olan podInstall görevi çalıştırılır. Oluşturulan .xcworkspace, Podfile'ın yanında proje kökünde yer alacaktır.

Eklenti, Xcode Derleme Aşamaları ile entegre olur. Bir iOS uygulaması derlenirken, Xcode embedAndSignAppleFrameworkForXcode'u çalıştırır — bu, Kotlin/Native framework'ünü uygulama paketine kopyalayan bir görevdir. CocoaPods Plugin, .xcworkspace oluşturulurken bu derleme aşamasını otomatik olarak ekler. .xcworkspace oluşturulduysa, pod bağımlılıklarıyla doğru derleme için .xcodeproj yerine açılmalıdır.

Kod örnekleri: pod yapılandırması

CocoaPods Plugin'de pod bildirmenin çeşitli senaryolarını inceleyelim. Temel durum, belirtilen bir sürümle CocoaPods Trunk'tan genel bir pod bağlamaktır. Daha karmaşık senaryolar, özel podspec, yerel podlar ve git depolarından podların kullanımını içerir.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // CocoaPods Trunk'tan genel pod
        pod("Alamofire") { version = "5.9.0" }

        // Operatörlü özel sürüm
        pod("SnapKit") { version = "~> 5.6" }

        // Özel depodan pod
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Yerel pod (yollu)
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Podları bağlamak, yapılandırmanın yalnızca bir parçasıdır. Eklenti ayrıca diğer Kotlin modüllerinden iOS framework'üne bağımlılıkların dışa aktarılmasına da izin verir. export(project(":core")) işlevi, :core modülünün tüm genel API'lerinin oluşturulan framework'ün Objective-C başlığından erişilebilir olması gerektiğini belirtir. Bu, paylaşılan Kotlin kodu başka bir modülden sınıflar kullandığında ve bunların Swift'ten erişilebilir olması gerektiğinde gereklidir.

cocoapods {
    framework {
        baseName = "Shared"
        // Modülleri iOS framework'üne dışa aktar
        export(project(":network"))
        export(project(":domain"))

        // Statik veya dinamik bağlama
        isStatic = true
    }

    // Dışa aktarılan modüller için gerekli pod
    pod("Moya") { version = "15.0" }
}

Derleme ve test

Yapılandırmadan sonra, Podfile oluşturmak ve bağımlılıkları yüklemek için podInstall çalıştırmanız gerekir. Ardından oluşturulan .xcworkspace Xcode'da açılır ve uygulama standart şekilde derlenebilir. CI/CD için, derleme makinesinde CocoaPods ve Ruby'nin yüklü olduğundan emin olun. Eklenti, CI ortamında çalışmak için --no-daemon bayrağını destekler.

// Podların yüklenmesi Podfile + xcworkspace oluşturur
./gradlew :shared:podInstall

// Test için hata ayıklama framework'ü derle
./gradlew :shared:podBuildDebugFramework

// Komut satırından tam iOS derlemesi
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM), Apple'ın alternatif bağımlılık yöneticisidir ve popülerlik kazanarak iOS topluluğunda CocoaPods'un yerini yavaş yavaş almaktadır. Ancak CocoaPods Plugin, birkaç nedenden dolayı geçerliliğini korumaktadır: SPM, KMM bağlamında dinamik framework'leri desteklemez ve SPM aracılığıyla Kotlin/Native framework entegrasyonu ek yapılandırma gerektirir. CocoaPods Plugin daha olgun ve belgelenmiş bir entegrasyon yolu sağlar.

CocoaPods Plugin ve doğrudan SPM entegrasyonunun karşılaştırması, birincisinin otomasyonda, ikincisinin ise yerel Apple desteğinde kazandığını gösterir. CocoaPods Plugin otomatik olarak Podfile oluşturur, sürümleri yönetir ve Xcode Derleme Aşamalarını yapılandırır. SPM, Package.swift aracılığıyla Kotlin framework'ünün manuel olarak bağlanmasını gerektirir, bu da büyük KMM projelerinde bakımı daha zordur. JetBrains, Kotlin/Native için SPM desteği üzerinde çalışmaktadır, ancak 2025 itibarıyla SPM entegrasyonu deneysel olarak kalmaktadır.

Yaygın sorunlar ve çözümleri

CocoaPods Plugin kullanırken, KMM geliştiricileri birkaç tipik sorunla karşılaşır. Pod sürüm çakışması en yaygın sorundur; iki pod aynı bağımlılığın farklı sürümlerini gerektirdiğinde ortaya çıkar. Çözüm, pod("Dependency") { version = "x.x" } aracılığıyla çakışan bağımlılığın sürümünü açıkça belirtmektir. İkinci yaygın durum, bir pod'un KMM projesinin minimum sürümünden daha yeni bir iOS SDK gerektirdiği sürüm uyumsuzluğudur.

.xcworkspace ile ilgili sorunlar, eklentiyi yapılandırdıktan sonra .xcodeproj yerine .xcworkspace açılmazsa ortaya çıkar. Eklenti, podInstall günlüklerinde bu konuda uyarır. Diğer sık görülen bir hata, geliştirme makinesinde CocoaPods'un bulunmamasıdır. Eklenti, podInstall'ı çalıştırmadan önce pod komutunun varlığını kontrol eder ve net bir hata mesajı görüntüler. CI/CD için CocoaPods'u yükleyin: gem install cocoapods.

// Sürüm çakışmasını çöz
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Çakışmayı açıkça çöz
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Gradle aracılığıyla CocoaPods kurulumunu kontrol et
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods sürümü: $result")
    }
}

podInstall hata ayıklama

podInstall başarısız olursa, ayrıntılı çıktı için --info bayrağını kullanın: ./gradlew podInstall --info. Eklenti her adımı günlüğe kaydeder: Podfile oluşturma, pod install yürütme, Podfile.lock ayrıştırma. Çoğu zaman hatalar ağ sorunlarıyla (CocoaPods Trunk kullanılamıyor) veya yanlış Podfile sözdizimiyle ilgilidir. Bu gibi durumlarda, CocoaPods'tan daha ayrıntılı bir hata mesajı almak için proje kökünde manuel olarak pod install çalıştırmayı deneyin.