CocoaPods Plugin — یہ کیا ہے، KMM کے لیے پلگ ان اور سیٹ اپ

CocoaPods Plugin کیا ہے؟

CocoaPods Plugin (kotlin.cocoapods کے نام سے بھی جانا جاتا ہے) CocoaPods کو Kotlin Multiplatform Mobile کے ساتھ ضم کرنے کے لیے JetBrains کا ایک سرکاری پلگ ان ہے۔ پلگ ان Kotlin Gradle DSL کا حصہ ہے اور براہ راست KMM ماڈیول کے build.gradle.kts میں ترتیب دیا جاتا ہے۔ یہ Podfile کی تخلیق اور دیکھ بھال، .xcworkspace کی تخلیق، اور pod انحصارات کے انتظام کو خودکار بناتا ہے، دستی Xcode پروجیکٹ ترتیب کی ضرورت کو ختم کرتا ہے۔

CocoaPods Plugin سے پہلے، KMM ڈویلپرز کو دستی طور پر Podfile بنانا، pod install چلانا، bridge headers ترتیب دینا، اور Gradle انحصارات سے الگ pod ورژن کا سراغ لگانا پڑتا تھا۔ اس سے ورژن غیر ہم آہنگی اور CI/CD پائپ لائنوں میں مشکلات پیدا ہوتی تھیں۔ پلگ ان نے iOS انحصار کے انتظام کو Android ماڈیولز میں Gradle انحصار کے انتظام جتنا آسان بنا کر ان مسائل کو حل کیا۔

پلگ ان CocoaPods Trunk سے عوامی pods اور نجی ذخیروں سے حسب ضرورت pods دونوں کو سپورٹ کرتا ہے۔ مقامی Podspec اور git پر مبنی ذخیروں کے ساتھ کام کرنا بھی سپورٹ کیا جاتا ہے۔ پلگ ان Kotlin 1.6.0 اور اس سے اوپر کے ورژنز کے ساتھ مطابقت رکھتا ہے، اور ڈویلپمنٹ مشین پر CocoaPods (gem install cocoapods) انسٹال ہونا ضروری ہے۔

CocoaPods Plugin کیسے کام کرتا ہے

CocoaPods Plugin Gradle ٹاسک گراف کی سطح پر کام کرتا ہے، CocoaPods کے ساتھ کام کرنے کے لیے خصوصی ٹاسک شامل کرتا ہے۔ اہم ٹاسک میں podInstall (pods انسٹال کرنا)، podGenXcodeWorkspace (.xcworkspace بنانا) اور podBuildDebugFramework (فریم ورک کا Debug ورژن بنانا) شامل ہیں۔ پلگ ان build.gradle.kts میں cocoapods سیکشن کا تجزیہ کرتا ہے، اعلان کردہ انحصارات کی بنیاد پر Podfile بناتا ہے، اور مطلوبہ پیرامیٹرز کے ساتھ pod install چلاتا ہے۔

پلگ ان کے فن تعمیر میں تین اجزاء شامل ہیں: build.gradle.kts کے لیے DSL ایکسٹینشن، Podfile بنانے کے لیے Podfile جنریٹر، اور .xcworkspace ترتیب دینے کے لیے Xcode انضمام پرت۔ DSL ایکسٹینشن انحصارات کا اعلان کرنے کے لیے نیسٹڈ pod() فنکشنز، نجی ذخیروں کی وضاحت کرنے کے لیے specRepo()، اور آؤٹ پٹ فریم ورک ترتیب دینے کے لیے framework { } کے ساتھ ایک cocoapods { } بلاک فراہم کرتا ہے۔ Podfile جنریٹر ان اعلانات کو Ruby نحو میں ترجمہ کرتا ہے جسے 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"
        }
    }
}

podInstall ٹاسک کا لائف سائیکل

podInstall پر عمل کرتے ہوئے، پلگ ان ترتیبی طور پر: پروجیکٹ روٹ میں Podfile بناتا ہے، کمانڈ لائن کے ذریعے pod install چلاتا ہے، .xcworkspace بناتا ہے، تصدیق کرتا ہے کہ pod ورژن اعلان کردہ ورژن سے مطابقت رکھتے ہیں، اور Podfile.lock کو کیش کرتا ہے۔ ترتیب میں تبدیلی کے بغیر بعد کے رنز میں، podInstall چھوڑ دیا جاتا ہے اگر Podfile.lock تبدیل نہیں ہوا ہے۔ یہ CI/CD میں وقت بچاتا ہے، جہاں صاف انسٹالیشن میں pod install کو 2-3 منٹ لگ سکتے ہیں۔

KMM پروجیکٹ میں CocoaPods Plugin سیٹ اپ کرنا

CocoaPods Plugin سیٹ اپ کرنے کے لیے کئی مراحل درکار ہیں۔ ڈویلپمنٹ مشین پر CocoaPods انسٹال کرنا (gem install cocoapods) ایک شرط ہے۔ پھر، shared ماڈیول کے build.gradle.kts میں، فریم ورک ترتیب اور انحصارات کے ساتھ ایک cocoapods { } بلاک شامل کیا جاتا ہے۔ ترتیب کے بعد، podInstall ٹاسک چلائیں، جو Podfile بنائے گا اور pods انسٹال کرے گا۔ بنایا گیا .xcworkspace Podfile کے ساتھ پروجیکٹ روٹ میں واقع ہوگا۔

پلگ ان Xcode بلڈ فیزز کے ساتھ ضم ہوتا ہے۔ iOS ایپ بناتے وقت، Xcode embedAndSignAppleFrameworkForXcode چلاتا ہے — ایک ٹاسک جو Kotlin/Native فریم ورک کو ایپ بنڈل میں کاپی کرتا ہے۔ CocoaPods Plugin .xcworkspace بناتے وقت اس بلڈ فیز کو خود بخود شامل کرتا ہے۔ اگر .xcworkspace بنایا گیا ہے، تو pod انحصارات کے ساتھ درست بلڈ کے لیے اسے .xcodeproj کی بجائے کھولا جانا چاہیے۔

کوڈ مثالیں: pod ترتیب

آئیے CocoaPods Plugin میں pods کا اعلان کرنے کے مختلف منظرناموں کا جائزہ لیں۔ بنیادی صورت ایک مخصوص ورژن کے ساتھ CocoaPods Trunk سے عوامی pod جوڑنا ہے۔ مزید پیچیدہ منظرناموں میں حسب ضرورت podspec، مقامی pods، اور git ذخیروں سے pods کا استعمال شامل ہے۔

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // CocoaPods Trunk سے عوامی pod
        pod("Alamofire") { version = "5.9.0" }

        // آپریٹر کے ساتھ حسب ضرورت ورژن
        pod("SnapKit") { version = "~> 5.6" }

        // نجی ذخیرے سے pod
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // راستے کے ساتھ مقامی pod
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // git ذخیرے سے pod
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

pods جوڑنا ترتیب کا صرف ایک حصہ ہے۔ پلگ ان آپ کو دیگر Kotlin ماڈیولز سے iOS فریم ورک میں انحصارات برآمد کرنے کی بھی اجازت دیتا ہے۔ export(project(":core")) فنکشن بتاتا ہے کہ :core ماڈیول کے تمام عوامی APIs بنائے گئے فریم ورک کے Objective-C ہیڈر سے قابل رسائی ہونے چاہئیں۔ یہ ضروری ہے جب مشترکہ Kotlin کوڈ کسی دوسرے ماڈیول کی کلاسز استعمال کرتا ہے اور انہیں Swift سے قابل رسائی ہونے کی ضرورت ہوتی ہے۔

cocoapods {
    framework {
        baseName = "Shared"
        // ماڈیولز کو iOS فریم ورک میں برآمد کریں
        export(project(":network"))
        export(project(":domain"))

        // جامد یا متحرک لنکنگ
        isStatic = true
    }

    // برآمد کردہ ماڈیولز کے لیے مطلوبہ pod
    pod("Moya") { version = "15.0" }
}

بلڈ اور جانچ

ترتیب کے بعد، Podfile بنانے اور انحصارات انسٹال کرنے کے لیے podInstall چلانا ضروری ہے۔ پھر بنایا گیا .xcworkspace Xcode میں کھولا جاتا ہے، جہاں ایپ معیاری طریقے سے بنائی جا سکتی ہے۔ CI/CD کے لیے، یقینی بنائیں کہ بلڈ مشین پر CocoaPods اور Ruby انسٹال ہیں۔ پلگ ان CI ماحول میں کام کرنے کے لیے --no-daemon پرچم کو سپورٹ کرتا ہے۔

// pods انسٹال کرنے سے Podfile + xcworkspace بنتا ہے
./gradlew :shared:podInstall

// جانچ کے لیے ڈیبگ فریم ورک بنائیں
./gradlew :shared:podBuildDebugFramework

// کمانڈ لائن سے مکمل iOS بلڈ
xcodebuild -workspace ios-app.xcworkspace \
    -scheme ios-app -configuration Debug

CocoaPods Plugin بمقابلہ Swift Package Manager

Swift Package Manager (SPM) Apple کا ایک متبادل انحصار مینیجر ہے جو مقبولیت حاصل کر رہا ہے اور آہستہ آہستہ iOS کمیونٹی میں CocoaPods کی جگہ لے رہا ہے۔ تاہم، CocoaPods Plugin کئی وجوہات کی بنا پر متعلقہ ہے: SPM KMM سیاق و سباق میں متحرک فریم ورک کو سپورٹ نہیں کرتا، اور SPM کے ذریعے Kotlin/Native فریم ورک کے انضمام کے لیے اضافی ترتیب درکار ہے۔ CocoaPods Plugin ایک زیادہ پختہ اور دستاویزی انضمام کا راستہ فراہم کرتا ہے۔

CocoaPods Plugin اور براہ راست SPM انضمام کا موازنہ ظاہر کرتا ہے کہ پہلا آٹومیشن میں جیتتا ہے، جبکہ دوسرا مقامی Apple سپورٹ میں جیتتا ہے۔ CocoaPods Plugin خود بخود Podfile بناتا ہے، ورژن کا انتظام کرتا ہے اور Xcode بلڈ فیزز ترتیب دیتا ہے۔ SPM کو Package.swift کے ذریعے Kotlin فریم ورک کو دستی طور پر منسلک کرنے کی ضرورت ہوتی ہے، جو بڑے KMM پروجیکٹس کے لیے برقرار رکھنا زیادہ مشکل ہے۔ JetBrains Kotlin/Native کے لیے SPM سپورٹ پر کام کر رہا ہے، لیکن 2025 تک SPM انضمام تجرباتی ہے۔

عام مسائل اور حل

CocoaPods Plugin استعمال کرتے وقت، KMM ڈویلپرز کو کئی عام مسائل کا سامنا کرنا پڑتا ہے۔ pod ورژن کا تصادم سب سے عام مسئلہ ہے، جب دو pods کو ایک ہی انحصار کے مختلف ورژن درکار ہوتے ہیں۔ حل pod("Dependency") { version = "x.x" } کے ذریعے متصادم انحصار کے ورژن کی واضح طور پر وضاحت کرنا ہے۔ دوسری عام صورت ورژن کی عدم مطابقت ہے، جب ایک pod کو KMM پروجیکٹ کے کم از کم ورژن سے زیادہ نئے iOS SDK کی ضرورت ہوتی ہے۔

.xcworkspace کے ساتھ مسائل اس وقت پیدا ہوتے ہیں جب پلگ ان ترتیب دینے کے بعد .xcodeproj کو .xcworkspace کی بجائے کھولا جاتا ہے۔ پلگ ان podInstall لاگز میں اس بارے میں خبردار کرتا ہے۔ ایک اور بار بار آنے والی غلطی ڈویلپمنٹ مشین پر CocoaPods کی عدم موجودگی ہے۔ پلگ ان podInstall چلانے سے پہلے pod کمانڈ کی موجودگی کی جانچ کرتا ہے اور واضح غلطی کا پیغام دکھاتا ہے۔ CI/CD کے لیے، CocoaPods انسٹال کریں: gem install cocoapods۔

// ورژن تصادم حل کریں
cocoapods {
    pod("Alamofire") { version = "5.9.0" }
    // تصادم کو واضح طور پر حل کریں
    pod("Alamofire") {
        version = "5.9.0"
        options[name] = mapOf("force" to true)
    }
}

// Gradle کے ذریعے CocoaPods انسٹالیشن چیک کریں
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("CocoaPods ورژن: $result")
    }
}

podInstall کی ڈیبگنگ

اگر podInstall ناکام ہو جائے تو، تفصیلی آؤٹ پٹ کے لیے --info پرچم استعمال کریں: ./gradlew podInstall --info۔ پلگ ان ہر مرحلے کو لاگ کرتا ہے: Podfile تخلیق، podInstall پر عمل، Podfile.lock پارسنگ۔ اکثر، غلطیاں نیٹ ورک کے مسائل (CocoaPods Trunk دستیاب نہیں) یا غلط Podfile نحو سے متعلق ہوتی ہیں۔ ایسی صورتوں میں، CocoaPods سے زیادہ تفصیلی غلطی کا پیغام حاصل کرنے کے لیے پروجیکٹ روٹ میں دستی طور پر pod install چلانے کی کوشش کریں۔