CocoaPods Plugin — این چیست، پلاگین برای KMM و تنظیمات

CocoaPods Plugin چیست؟

CocoaPods Plugin (همچنین به عنوان kotlin.cocoapods شناخته می‌شود) — پلاگین رسمی JetBrains برای یکپارچه‌سازی CocoaPods با Kotlin Multiplatform Mobile است. پلاگین بخشی از Kotlin Gradle DSL است و مستقیماً در build.gradle.kts ماژول KMM پیکربندی می‌شود. این پلاگین ایجاد و نگهداری Podfile، تولید .xcworkspace و مدیریت وابستگی‌های پاد را خودکار می‌کند و توسعه‌دهنده را از پیکربندی دستی پروژه Xcode بی‌نیاز می‌سازد.

قبل از ظهور CocoaPods Plugin، توسعه‌دهندگان KMM مجبور بودند به صورت دستی Podfile ایجاد کنند، pod install را اجرا کنند، bridge-headerها را پیکربندی کنند و نسخه‌های پاد را جدا از وابستگی‌های Gradle پیگیری کنند. این امر منجر به عدم هماهنگی نسخه‌ها و مشکلات در خطوط لوله CI/CD می‌شد. پلاگین این مشکلات را حل کرد و مدیریت وابستگی‌های iOS را به سادگی مدیریت وابستگی‌های Gradle در ماژول‌های Android کرد.

پلاگین هم پادهای عمومی از CocoaPods Trunk و هم پادهای سفارشی از مخازن خصوصی را پشتیبانی می‌کند. کار با Podspec محلی و مخازن مبتنی بر git نیز پشتیبانی می‌شود. پلاگین با نسخه‌های Kotlin 1.6.0 و بالاتر سازگار است و همچنین نیاز به نصب CocoaPods (gem install cocoapods) بر روی ماشین توسعه‌دهنده دارد.

CocoaPods Plugin چگونه کار می‌کند

CocoaPods Plugin در سطح گراف وظایف Gradle کار می‌کند و وظایف تخصصی برای کار با CocoaPods اضافه می‌کند. وظایف اصلی شامل podInstall (نصب پادها)، podGenXcodeWorkspace (تولید .xcworkspace) و podBuildDebugFramework (ساخت نسخه دیباگ فریم‌ورک) است. پلاگین بخش cocoapods را در build.gradle.kts تحلیل می‌کند، Podfile را بر اساس وابستگی‌های اعلام شده ایجاد می‌کند و pod install را با پارامترهای لازم اجرا می‌کند.

معماری پلاگین شامل سه مؤلفه است: توسعه DSL برای build.gradle.kts، تولیدکننده Podfile برای ایجاد Podfile و لایه یکپارچه‌سازی Xcode برای پیکربندی .xcworkspace. توسعه DSL بلوک cocoapods { } را با توابع تو در توی pod() برای اعلام وابستگی‌ها، specRepo() برای مشخص کردن مخازن خصوصی و framework { } برای پیکربندی فریم‌ورک خروجی فراهم می‌کند. تولیدکننده 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 را تولید می‌کند، تطابق نسخه‌های پاد با نسخه‌های اعلام شده را بررسی می‌کند و Podfile.lock را ذخیره می‌کند. در اجرای مجدد بدون تغییر در پیکربندی، اگر Podfile.lock تغییر نکرده باشد، podInstall رد می‌شود. این کار در CI/CD که pod install ممکن است 2-3 دقیقه برای نصب تمیز طول بکشد، صرفه‌جویی در زمان می‌کند.

راه‌اندازی CocoaPods Plugin در پروژه KMM

برای راه‌اندازی CocoaPods Plugin باید چند مرحله انجام شود. نصب CocoaPods بر روی ماشین توسعه‌دهنده (gem install cocoapods) یک شرط اجباری است. سپس در build.gradle.kts ماژول shared بلوک cocoapods { } با پیکربندی فریم‌ورک و وابستگی‌ها اضافه می‌شود. پس از پیکربندی، باید وظیفه podInstall اجرا شود که Podfile را ایجاد کرده و پادها را نصب می‌کند. .xcworkspace تولید شده در ریشه پروژه در کنار Podfile قرار خواهد گرفت.

پلاگین با مراحل ساخت Xcode یکپارچه می‌شود. هنگام ساخت برنامه iOS، Xcode وظیفه embedAndSignAppleFrameworkForXcode را اجرا می‌کند که فریم‌ورک Kotlin/Native را در بسته برنامه کپی می‌کند. CocoaPods Plugin این مرحله ساخت را به طور خودکار هنگام تولید .xcworkspace اضافه می‌کند. اگر .xcworkspace تولید شده است، برای ساخت صحیح با وابستگی‌های پاد باید به جای .xcodeproj آن را باز کنید.

نمونه کد: پیکربندی پادها

سناریوهای مختلف اعلام پادها در CocoaPods Plugin را بررسی می‌کنیم. حالت پایه — اتصال پاد عمومی از CocoaPods Trunk با ذکر نسخه. سناریوهای پیچیده‌تر شامل استفاده از podspec سفارشی، پادهای محلی و پادهای مخازن git است.

kotlin {
    iosArm64()
    iosSimulatorArm64()

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

        // پاد عمومی از CocoaPods Trunk
        pod("Alamofire") { version = "5.9.0" }

        // نسخه سفارشی با عملگر
        pod("SnapKit") { version = "~> 5.6" }

        // پاد از مخزن خصوصی
        specRepo("https://git.itsectr.com/specs.git",
            "internal-specs")
        pod("InternalAnalyticsPod")

        // پاد محلی با مسیر
        pod(name = "CustomPod",
            localPath = "./ios-pods/CustomPod")

        // پاد از مخزن git
        pod(name = "PrivateSDK",
            git = "https://git.itsectr.com/ios/sdk.git",
            tag = "2.1.0")
    }
}

اتصال پادها تنها بخشی از پیکربندی است. پلاگین همچنین امکان صادرات وابستگی‌ها از سایر ماژول‌های Kotlin به فریم‌ورک iOS را فراهم می‌کند. تابع export(project(":core")) مشخص می‌کند که تمام APIهای عمومی ماژول :core باید از هدر Objective-C فریم‌ورک تولید شده قابل دسترسی باشند. این زمانی ضروری است که کد مشترک Kotlin از کلاس‌های ماژول دیگر استفاده می‌کند و آنها باید از Swift قابل دسترسی باشند.

cocoapods {
    framework {
        baseName = "Shared"
        // صادرات ماژول‌ها به فریم‌ورک iOS
        export(project(":network"))
        export(project(":domain"))

        // اتصال ایستا یا پویا
        isStatic = true
    }

    // پاد مورد نیاز برای ماژول‌های صادر شده
    pod("Moya") { version = "15.0" }
}

ساخت و تست

پس از پیکربندی، باید podInstall را برای تولید Podfile و نصب وابستگی‌ها اجرا کنید. سپس .xcworkspace تولید شده در Xcode باز می‌شود، جایی که می‌توان برنامه را به روش استاندارد ساخت. برای CI/CD باید مطمئن شوید که CocoaPods و Ruby بر روی ماشین ساخت نصب شده‌اند. پلاگین پرچم --no-daemon را برای کار در محیط CI پشتیبانی می‌کند.

// نصب پادها 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 است که محبوبیت پیدا می‌کند و به تدریج CocoaPods را در جامعه iOS کنار می‌زند. با این حال CocoaPods Plugin به چند دلیل همچنان مرتبط است: SPM از فریم‌ورک‌های پویا در زمینه KMM پشتیبانی نمی‌کند و یکپارچه‌سازی فریم‌ورک Kotlin/Native از طریق SPM نیاز به پیکربندی اضافی دارد. CocoaPods Plugin مسیر یکپارچه‌سازی بالغ‌تر و مستندتری را ارائه می‌دهد.

مقایسه CocoaPods Plugin و یکپارچه‌سازی مستقیم از طریق SPM نشان می‌دهد که اولی در خودکارسازی برنده است و دومی در پشتیبانی بومی Apple. CocoaPods Plugin به طور خودکار Podfile را تولید می‌کند، نسخه‌ها را مدیریت می‌کند و مراحل ساخت Xcode را پیکربندی می‌کند. SPM نیاز به اتصال دستی فریم‌ورک Kotlin از طریق Package.swift دارد که نگهداری آن برای پروژه‌های بزرگ KMM دشوارتر است. JetBrains روی پشتیبانی SPM برای Kotlin/Native کار می‌کند، اما تا سال 2025 یکپارچه‌سازی SPM تجربی باقی می‌ماند.

مشکلات رایج و راه‌حل‌ها

هنگام استفاده از CocoaPods Plugin، توسعه‌دهندگان KMM با چند مشکل رایج مواجه می‌شوند. تعارض نسخه پادها — رایج‌ترین مشکل، زمانی که دو پاد نسخه‌های مختلف یک وابستگی را نیاز دارند. راه‌حل مشخص کردن صریح نسخه وابستگی متعارض از طریق pod("Dependency") { version = "x.x" } است. دومین مورد رایج — ناسازگاری نسخه، زمانی که پاد به iOS SDK جدیدتری نسبت به حداقل نسخه پروژه KMM نیاز دارد.

مشکلات با .xcworkspace زمانی رخ می‌دهد که پس از راه‌اندازی پلاگین به جای .xcworkspace، .xcodeproj باز شود. پلاگین در لاگ‌های 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)
    }
}

// بررسی نصب CocoaPods از طریق Gradle
tasks.register("checkCocoapods") {
    doLast {
        val result = "pod --version".runCommand()
        println("نسخه CocoaPods: $result")
    }
}

اشکال‌زدایی podInstall

اگر podInstall با خطا به پایان رسید، از پرچم --info برای خروجی دقیق استفاده کنید: ./gradlew podInstall --info. پلاگین هر مرحله را ثبت می‌کند: تولید Podfile، اجرای pod install، تجزیه Podfile.lock. اغلب خطاها مربوط به مشکلات شبکه (عدم دسترسی به CocoaPods Trunk) یا نحو نادرست Podfile است. در چنین مواردی، سعی کنید pod install را به صورت دستی در ریشه پروژه اجرا کنید تا پیام خطای دقیق‌تری از CocoaPods دریافت کنید.