CocoaPods Plugin — bu nədir, KMM üçün plagin və konfiqurasiya

CocoaPods Plugin nədir?

CocoaPods Plugin (həmçinin kotlin.cocoapods kimi tanınır) — CocoaPods-u Kotlin Multiplatform Mobile ilə inteqrasiya etmək üçün JetBrains-in rəsmi plaginidir. Plagin Kotlin Gradle DSL-in bir hissəsidir və birbaşa KMM modulunun build.gradle.kts-də konfiqurasiya olunur. O, Podfile-ın yaradılması və saxlanmasını, .xcworkspace-in generasiyasını və pod asılılıqlarının idarə edilməsini avtomatlaşdırır, tərtibatçını Xcode layihəsinin əl ilə konfiqurasiyasından azad edir.

CocoaPods Plugin meydana gəlməzdən əvvəl, KMM tərtibatçıları Podfile-ı əl ilə yaratmağa, pod install-i işə salmağa, bridge-headerları konfiqurasiya etməyə və pod versiyalarını Gradle asılılıqlarından ayrı izləməyə məcbur idilər. Bu, versiyaların desinxronizasiyasına və CI/CD pipeline-larında çətinliklərə səbəb olurdu. Plagin bu problemləri həll etdi, iOS asılılıqlarının idarə edilməsini Android modullarında Gradle asılılıqlarının idarə edilməsi qədər sadə etdi.

Plagin həm CocoaPods Trunk-dən ictimai podları, həm də şəxsi repozitoriyalardan xüsusi podları dəstəkləyir. Yerli Podspec və git əsaslı repozitoriyalarla iş də dəstəklənir. Plagin Kotlin 1.6.0 və daha yuxarı versiyaları ilə uyğundur, həmçinin tərtibatçı maşınında CocoaPods-un quraşdırılmasını tələb edir (gem install cocoapods).

CocoaPods Plugin necə işləyir

CocoaPods Plugin Gradle task-qrafiki səviyyəsində işləyir, CocoaPods ilə iş üçün ixtisaslaşmış tapşırıqlar əlavə edir. Əsas tapşırıqlara podInstall (podların quraşdırılması), podGenXcodeWorkspace (.xcworkspace-in yaradılması) və podBuildDebugFramework (debug framework versiyasının qurulması) daxildir. Plagin build.gradle.kts-də cocoapods bölməsini təhlil edir, bəyan edilmiş asılılıqlar əsasında Podfile yaradır və lazımi parametrlərlə pod install-i işə salır.

Plaginin arxitekturası üç komponentdən ibarətdir: build.gradle.kts üçün DSL genişlənməsi, Podfile yaratmaq üçün Podfile Generator və .xcworkspace-i konfiqurasiya etmək üçün Xcode İnteqrasiya Təbəqəsi. DSL genişlənməsi asılılıqları bəyan etmək üçün pod() funksiyaları, şəxsi repozitoriyaları göstərmək üçün specRepo() və çıxış framework-unu konfiqurasiya etmək üçün framework { } olan cocoapods { } blokunu təmin edir. Podfile Generator bu bəyanatları CocoaPods üçün başa düşülən Ruby sintaksisinə tərcümə edir.

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 tapşırığının həyat dövrü

podInstall icra edilərkən, plagin ardıcıl olaraq: layihənin kökündə Podfile yaradır, komanda sətri vasitəsilə pod install-i işə salır, .xcworkspace yaradır, pod versiyalarının bəyan edilənlərə uyğunluğunu yoxlayır və Podfile.lock-u keşləyir. Konfiqurasiyada dəyişiklik olmadan təkrar işə salındıqda, Podfile.lock dəyişməyibsə podInstall buraxılır. Bu, pod install-in təmiz qurulmada 2-3 dəqiqəyə qədər çəkə biləcəyi CI/CD-də vaxta qənaət edir.

KMM layihəsində CocoaPods Plugin-in qurulması

CocoaPods Plugin-in qurulması üçün bir neçə addım yerinə yetirilməlidir. Tərtibatçı maşınında CocoaPods-un quraşdırılması (gem install cocoapods) məcburi şərtdir. Daha sonra shared modulunun build.gradle.kts-də framework və asılılıqların konfiqurasiyası ilə cocoapods { } bloku əlavə edilir. Konfiqurasiyadan sonra Podfile yaradacaq və podları quraşdıracaq podInstall tapşırığı icra edilməlidir. Yaradılan .xcworkspace Podfile ilə yanaşı layihənin kök kataloqunda yerləşəcək.

Plagin Xcode Build Phases ilə inteqrasiya olunur. iOS tətbiqi qurularkən, Xcode embedAndSignAppleFrameworkForXcode — Kotlin/Native framework-unu tətbiq paketinə kopyalayan tapşırığı işə salır. CocoaPods Plugin bu build phase-i .xcworkspace yaradılarkən avtomatik əlavə edir. Əgər .xcworkspace yaradılıbsa, pod asılılıqları ilə düzgün qurma üçün .xcodeproj əvəzinə onu açmaq lazımdır.

Kod nümunələri: podların konfiqurasiyası

CocoaPods Plugin-də podların bəyan edilməsinin müxtəlif ssenarilərini nəzərdən keçirək. Əsas hal — versiya göstərilməklə CocoaPods Trunk-dən ictimai podun qoşulması. Daha mürəkkəb ssenarilərə xüsusi podspec, lokal podlar və git repozitoriyalarından podların istifadəsi daxildir.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // CocoaPods Trunk-dən ictimai pod
        pod("Alamofire") { version = "5.9.0" }

        // Operatorla xüsusi versiya
        pod("SnapKit") { version = "~> 5.6" }

        // Şəxsi repozitoriyadan pod
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Yolu olan lokal pod
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Podların qoşulması konfiqurasiyanın yalnız bir hissəsidir. Plagin həmçinin digər Kotlin modullarından asılılıqları iOS framework-unə ixrac etməyə imkan verir. export(project(":core")) funksiyası göstərir ki, :core modulunun bütün ictimai API-ləri yaradılan framework-un Objective-C başlığından əlçatan olmalıdır. Bu, ümumi Kotlin kodu başqa modulun siniflərini istifadə etdikdə və onlar Swift-dən əlçatan olmalı olduqda lazımdır.

cocoapods {
    framework {
        baseName = "Shared"
        // Modulları iOS framework-ə ixrac et
        export(project(":network"))
        export(project(":domain"))

        // Statik və ya dinamik birləşdirmə
        isStatic = true
    }

    // İxrac edilmiş modullar üçün tələb olunan pod
    pod("Moya") { version = "15.0" }
}

Qurma və test etmə

Konfiqurasiya qurulduqdan sonra Podfile yaratmaq və asılılıqları quraşdırmaq üçün podInstall icra edilməlidir. Daha sonra yaradılan .xcworkspace Xcode-da açılır, burada tətbiqi standart üsulla qurmaq olar. CI/CD üçün qurma maşınında CocoaPods və Ruby-nin quraşdırıldığından əmin olmaq lazımdır. Plagin CI mühitində iş üçün --no-daemon bayrağını dəstəkləyir.

// Podların quraşdırılması Podfile + xcworkspace yaradır
./gradlew :shared:podInstall

// Test üçün debug framework qur
./gradlew :shared:podBuildDebugFramework

// Komanda sətrindən tam iOS qurma
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — Apple-dan alternativ asılılıq meneceridir, populyarlıq qazanır və tədricən iOS icmasında CocoaPods-u əvəz edir. Lakin CocoaPods Plugin bir neçə səbəbə görə aktual qalır: SPM KMM kontekstində dinamik framework-ları dəstəkləmir, Kotlin/Native framework-unun SPM vasitəsilə inteqrasiyası isə əlavə konfiqurasiya tələb edir. CocoaPods Plugin daha yetkin və sənədləşdirilmiş inteqrasiya yolu təmin edir.

Müqayisə CocoaPods Plugin və SPM vasitəsilə birbaşa inteqrasiya göstərir ki, birincisi avtomatlaşdırmada, ikincisi isə Apple-ın yerli dəstəyində üstündür. CocoaPods Plugin avtomatik Podfile yaradır, versiyaları idarə edir və Xcode Build Phases-lərini konfiqurasiya edir. SPM Kotlin framework-unun Package.swift vasitəsilə əl ilə qoşulmasını tələb edir, bu da böyük KMM layihələri üçün dəstəklənməsi daha çətindir. JetBrains Kotlin/Native üçün SPM dəstəyi üzərində işləyir, lakin 2025-ci ilə qədər SPM inteqrasiyası eksperimental olaraq qalır.

Tipik problemlər və həllər

CocoaPods Plugin istifadə edərkən KMM tərtibatçıları bir neçə tipik problemlə qarşılaşırlar. Pod versiya konflikti — ən çox rast gəlinən problem, iki pod eyni asılılığın müxtəlif versiyalarını tələb etdikdə baş verir. Həll yolu pod("Dependency") { version = "x.x" } vasitəsilə konflikt edən asılılığın versiyasını açıq şəkildə göstərməkdir. İkinci ümumi hal — pod KMM layihəsinin minimum versiyasından daha yeni iOS SDK tələb etdikdə versiya uyğunsuzluğudur.

.xcworkspace ilə problemlər plagin qurulduqdan sonra .xcworkspace əvəzinə .xcodeproj açıldıqda yaranır. Plagin bu barədə podInstall jurnallarında xəbərdarlıq edir. Digər ümumi səhv — tərtibatçı maşınında CocoaPods-un olmamasıdır. Plagin podInstall-i işə salmazdan əvvəl pod əmrinin mövcudluğunu yoxlayır və başa düşülən səhv mesajı göstərir. CI/CD üçün CocoaPods-u quraşdırmaq lazımdır: gem install cocoapods.

// Versiya konfliktini həll et
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Konflikti açıq şəkildə həll et
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// CocoaPods quraşdırmasını Gradle vasitəsilə yoxla
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods versiyası: $result")
    }
}

podInstall-in sazlanması

Əgər podInstall xəta ilə bitərsə, ətraflı çıxış üçün --info bayrağından istifadə edin: ./gradlew podInstall --info. Plagin hər addımı jurnallaşdırır: Podfile generasiyası, pod install-in işə salınması, Podfile.lock-un təhlili. Ən çox xətalar şəbəkə problemləri (CocoaPods Trunk-ə çatılmazlıq) və ya Podfile-in səhv sintaksisi ilə bağlıdır. Belə hallarda, CocoaPods-dan daha ətraflı səhv mesajı almaq üçün layihənin kökündə pod install-i əl ilə işə salmağa cəhd edin.