CocoaPods Plugin — ano ito, plugin para sa KMM at pagsasaayos

Ano ang CocoaPods Plugin?

CocoaPods Plugin (kilala rin bilang kotlin.cocoapods) — ay ang opisyal na plugin ng JetBrains para sa pagsasama ng CocoaPods sa Kotlin Multiplatform Mobile. Ang plugin ay bahagi ng Kotlin Gradle DSL at direktang naka-configure sa build.gradle.kts ng KMM module. Awtomatiko nito ang paggawa at pagpapanatili ng Podfile, pagbuo ng .xcworkspace, at pamamahala ng mga dependency ng pod, pinapalaya ang developer mula sa manu-manong pagsasaayos ng Xcode project.

Bago ang pagdating ng CocoaPods Plugin, ang mga KMM developer ay napilitang gumawa ng Podfile nang manu-mano, patakbuhin ang pod install, i-configure ang mga bridge-header, at subaybayan ang mga bersyon ng pod nang hiwalay mula sa mga dependency ng Gradle. Ito ay humantong sa desynchronization ng bersyon at kahirapan sa mga pipeline ng CI/CD. Nalutas ng plugin ang mga problemang ito, ginawang kasing simple ng pamamahala ng mga dependency ng Gradle sa mga module ng Android ang pamamahala ng mga dependency ng iOS.

Sinusuportahan ng plugin ang parehong pampublikong pod mula sa CocoaPods Trunk at custom na pod mula sa pribadong repository. Ang pagtatrabaho sa lokal na Podspec at mga repository na nakabatay sa git ay sinusuportahan din. Ang plugin ay katugma sa mga bersyon ng Kotlin 1.6.0 at mas bago, at nangangailangan ng naka-install na CocoaPods (gem install cocoapods) sa machine ng developer.

Paano Gumagana ang CocoaPods Plugin

CocoaPods Plugin ay gumagana sa antas ng Gradle task-graph, nagdaragdag ng mga espesyalisadong gawain para sa pagtatrabaho sa CocoaPods. Ang mga pangunahing gawain ay kinabibilangan ng podInstall (pag-install ng pod), podGenXcodeWorkspace (pagbuo ng .xcworkspace), at podBuildDebugFramework (pagbuo ng debug na bersyon ng framework). Sinusuri ng plugin ang cocoapods section sa build.gradle.kts, gumagawa ng Podfile batay sa mga idineklarang dependency, at pinapatakbo ang pod install gamit ang mga kinakailangang parameter.

Ang arkitektura ng plugin ay may tatlong bahagi: DSL extension para sa build.gradle.kts, Podfile Generator para sa paggawa ng Podfile, at Xcode Integration Layer para sa pagsasaayos ng .xcworkspace. Ang DSL extension ay nagbibigay ng cocoapods { } block na may nested pod() function para sa pagdeklara ng mga dependency, specRepo() para sa pagtukoy ng pribadong repository, at framework { } para sa pagsasaayos ng output framework. Ang Podfile Generator ay nagsasalin ng mga deklarasyong ito sa Ruby syntax na naiintindihan ng 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"
        }
    }
}

Lifecycle ng podInstall Task

Kapag isinasagawa ang podInstall, ang plugin ay sunud-sunod na: bumubuo ng Podfile sa root ng project, pinapatakbo ang pod install sa pamamagitan ng command line, bumubuo ng .xcworkspace, sinusuri ang pagkakatugma ng mga bersyon ng pod sa idineklara, at nag-cache ng Podfile.lock. Sa muling pagpapatakbo nang walang pagbabago sa configuration, nilalaktawan ang podInstall kung hindi nagbago ang Podfile.lock. Ito ay nakakatipid ng oras sa CI/CD, kung saan ang pod install ay maaaring tumagal ng hanggang 2-3 minuto para sa malinis na pag-install.

Pagsasaayos ng CocoaPods Plugin sa KMM Project

Para sa pagsasaayos ng CocoaPods Plugin, kailangan gawin ang ilang hakbang. Pag-install ng CocoaPods sa machine ng developer (gem install cocoapods) ay isang mandatoryong kondisyon. Pagkatapos, sa build.gradle.kts ng shared module ay idinagdag ang cocoapods { } block na may configuration ng framework at dependencies. Pagkatapos ng configuration, ang podInstall task ay dapat isagawa, na gagawa ng Podfile at mag-i-install ng mga pod. Ang nabuong .xcworkspace ay matatagpuan sa root ng project sa tabi ng Podfile.

Ang plugin ay isinasama sa Xcode Build Phases. Kapag binuo ang iOS application, pinapatakbo ng Xcode ang embedAndSignAppleFrameworkForXcode — isang gawain na kumukopya ng Kotlin/Native framework sa app bundle. Awtomatikong idinadagdag ng CocoaPods Plugin ang build phase na ito kapag bumubuo ng .xcworkspace. Kung nabuo na ang .xcworkspace, dapat itong buksan sa halip na .xcodeproj para sa tamang compilation na may mga dependency ng pod.

Mga Halimbawa ng Code: Pagsasaayos ng mga Pod

Tingnan natin ang iba't ibang senaryo ng pagdeklara ng mga pod sa CocoaPods Plugin. Ang pangunahing kaso — pagkonekta ng pampublikong pod mula sa CocoaPods Trunk na may pagtukoy ng bersyon. Ang mas kumplikadong mga senaryo ay kinabibilangan ng paggamit ng custom na podspec, lokal na pod, at pod mula sa mga git repository.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // Pampublikong pod mula sa CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // Custom na bersyon na may operator
        pod("SnapKit") { version = "~> 5.6" }

        // Pod mula sa pribadong repository
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // Lokal na pod na may landas
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

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

Ang pagkonekta ng mga pod ay bahagi lamang ng configuration. Pinapayagan din ng plugin ang pag-export ng mga dependency mula sa iba pang Kotlin module papunta sa iOS framework. Ang function na export(project(":core")) ay nagpapahiwatig na ang lahat ng pampublikong API ng :core module ay dapat ma-access mula sa Objective-C header ng nabuong framework. Ito ay kinakailangan kapag ang shared Kotlin code ay gumagamit ng mga class mula sa ibang module at ang mga ito ay dapat ma-access mula sa Swift.

cocoapods {
    framework {
        baseName = "Shared"
        // I-export ang mga module sa iOS framework
        export(project(":network"))
        export(project(":domain"))

        // Static o dynamic na pagkonekta
        isStatic = true
    }

    // Pod na kinakailangan para sa mga na-export na module
    pod("Moya") { version = "15.0" }
}

Pagbuo at Pagsubok

Pagkatapos ng configuration, dapat isagawa ang podInstall upang makabuo ng Podfile at mag-install ng mga dependency. Pagkatapos, ang nabuong .xcworkspace ay bubuksan sa Xcode, kung saan ang application ay maaaring buuin sa karaniwang paraan. Para sa CI/CD, tiyakin na naka-install ang CocoaPods at Ruby sa build machine. Sinusuportahan ng plugin ang --no-daemon flag para sa pagtatrabaho sa CI environment.

// Pag-install ng pod ay bumubuo ng Podfile + xcworkspace
./gradlew :shared:podInstall

// Buuin ang debug framework para sa pagsubok
./gradlew :shared:podBuildDebugFramework

// Buong iOS build mula sa command line
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin vs Swift Package Manager

Swift Package Manager (SPM) — isang alternatibong tagapamahala ng dependency mula sa Apple, na nagiging popular at unti-unting pinapalitan ang CocoaPods sa iOS community. Gayunpaman, ang CocoaPods Plugin ay nananatiling may kaugnayan sa ilang kadahilanan: hindi sinusuportahan ng SPM ang mga dynamic na framework sa KMM context, at ang pagsasama ng Kotlin/Native framework sa pamamagitan ng SPM ay nangangailangan ng karagdagang configuration. Ang CocoaPods Plugin ay nagbibigay ng mas mature at dokumentadong landas ng pagsasama.

Paghahambing ng CocoaPods Plugin at direktang pagsasama sa pamamagitan ng SPM ay nagpapakita na ang una ay nananalo sa automation, at ang pangalawa — sa native na suporta ng Apple. Awtomatikong bumubuo ang CocoaPods Plugin ng Podfile, namamahala ng mga bersyon, at nag-configure ng Xcode Build Phases. Ang SPM ay nangangailangan ng manu-manong pagkonekta ng Kotlin framework sa pamamagitan ng Package.swift, na mas mahirap panatilihin para sa malalaking KMM project. Ang JetBrains ay gumagawa sa SPM support para sa Kotlin/Native, ngunit hanggang 2025 ang SPM integration ay nananatiling eksperimental.

Mga Karaniwang Problema at Solusyon

Kapag gumagamit ng CocoaPods Plugin, ang mga KMM developer ay nakakaharap ng ilang karaniwang problema. Salungatan ng bersyon ng pod — ang pinakakaraniwang problema, kapag ang dalawang pod ay nangangailangan ng magkaibang bersyon ng parehong dependency. Ang solusyon ay ang tahasang pagtukoy ng bersyon ng nagkakasalungatang dependency sa pamamagitan ng pod("Dependency") { version = "x.x" }. Ang pangalawang karaniwang kaso — hindi pagkakatugma ng bersyon, kapag ang isang pod ay nangangailangan ng mas bagong iOS SDK kaysa sa minimum na bersyon ng KMM project.

Mga problema sa .xcworkspace ay lumalabas kung bubuksan ang .xcodeproj sa halip na .xcworkspace pagkatapos ng configuration ng plugin. Nagbabala ang plugin tungkol dito sa mga log ng podInstall. Ang isa pang karaniwang error — ang kawalan ng CocoaPods sa machine ng developer. Sinusuri ng plugin ang pagkakaroon ng pod command bago patakbuhin ang podInstall at nagpapakita ng malinaw na mensahe ng error. Para sa CI/CD, i-install ang CocoaPods: gem install cocoapods.

// Lutasin ang salungatan ng bersyon
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // Lutasin ang salungatan nang tahasan
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Suriin ang pag-install ng CocoaPods sa pamamagitan ng Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("Bersyon ng CocoaPods: $result")
    }
}

Pag-debug ng podInstall

Kung ang podInstall ay nagtatapos sa error, gamitin ang --info flag para sa detalyadong output: ./gradlew podInstall --info. Ini-log ng plugin ang bawat hakbang: pagbuo ng Podfile, pagpapatakbo ng pod install, pag-parse ng Podfile.lock. Kadalasan, ang mga error ay nauugnay sa mga problema sa network (hindi maabot ang CocoaPods Trunk) o maling syntax ng Podfile. Sa mga ganitong kaso, subukang patakbuhin ang pod install nang manu-mano sa root ng project upang makakuha ng mas detalyadong mensahe ng error mula sa CocoaPods.