Carthage: چیست، مدیر وابستگی غیرمتمرکز

Carthage چیست؟

Carthage — یک مدیر وابستگی با معماری غیرمتمرکز است که در سال ۲۰۱۴ توسط توسعه‌دهندگان جامعه Swift ایجاد شده است. Carthage از رجیستری مرکزی مشخصات استفاده نمی‌کند — هر کتابخانه مستقیماً از مخزن Git از طریق URL یا نام در GitHub متصل می‌شود. Carthage کد منبع را بارگیری می‌کند، آن را به یک فریمورک باینری (.xcframework یا .framework) می‌سازد و یک مصنوع آماده برای ادغام دستی در پروژه Xcode در اختیار توسعه‌دهنده قرار می‌دهد.

معماری Carthage شامل سه مؤلفه است: ابزار خط فرمان carthage، فایل پیکربندی Cartfile و دایرکتوری Carthage/Build/ با فریمورک‌های ساخته شده. تفاوت اساسی Carthage با CocoaPods — عدم تغییر خودکار .xcodeproj است. Carthage .xcworkspace ایجاد نمی‌کند، فلگ‌های کامپایلر را تنظیم نمی‌کند و Pods.xcconfig تولید نمی‌کند. توسعه‌دهنده خودش فریمورک‌ها را از طریق Xcode به پروژه اضافه می‌کند که کنترل کاملی بر فرآیند ادغام می‌دهد.

Carthage از ساخت موازی وابستگی‌ها استفاده می‌کند که فرآیند را روی پردازنده‌های چند هسته‌ای به طور قابل توجهی سرعت می‌بخشد. هر وابستگی به عنوان یک target جداگانه ساخته می‌شود و Carthage به طور خودکار گراف وابستگی‌های انتقالی را حل کرده و آنها را به ترتیب صحیح می‌سازد. بر اساس بنچمارک‌های جامعه، Carthage ۱۵–۲۰ وابستگی را به طور متوسط در ۳۰–۶۰ ثانیه روی Macهای مدرن می‌سازد که برای پروژه‌های با تعداد زیادی کتابخانه سریع‌تر از CocoaPods است. Carthage از تمام پلتفرم‌های Apple پشتیبانی می‌کند: iOS، macOS، watchOS و tvOS، و از نسخه ۰٫۳۸ به بعد — ساخت .xcframework جهانی برای پشتیبانی از شبیه‌سازها و دستگاه‌های Apple Silicon.

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

Carthage مخزن Git هر وابستگی را کلون می‌کند، به نسخه مشخص شده (tag، commit یا branch) سوئیچ می‌کند و xcodebuild را برای ساخت فریمورک اجرا می‌کند. Carthage نوع پروژه Xcode (فریمورک، dynamic framework، کتابخانه استاتیک) را به طور خودکار بر اساس طرح ساخت تعیین می‌کند. اگر پروژه شامل چندین طرح باشد، Carthage از طرح پیش‌فرض (اولین به ترتیب حروف الفبا) استفاده می‌کند. پس از ساخت، Carthage فریمورک آماده را در Carthage/Build/ کپی می‌کند و فایل Cartfile.resolved را با تثبیت نسخه‌های دقیق ایجاد می‌کند. Carthage از کش کردن فریمورک‌های ساخته شده پشتیبانی می‌کند — ساخت مجدد بدون تغییر وابستگی‌ها انجام نمی‌شود.

وابستگی‌های انتقالی در Carthage از طریق Cartfile.resolved مدیریت می‌شوند: Carthage گراف تمام وابستگی‌های لازم را می‌سازد و آنها را به ترتیب صحیح می‌چیند. اگر دو کتابخانه به یک کتابخانه شخص ثالث وابسته باشند، Carthage آن را یک بار ساخته و برای هر دو استفاده می‌کند. Carthage خطاهای ساخت را با مشخص کردن target خاص و دلیل اطلاع می‌دهد — این تشخیص مشکلات را ساده می‌کند.

Cartfile: ساختار، نحو و مثال‌ها

Cartfile — فایل پیکربندی به زبان Ruby (فرمت Cartfile) است که وابستگی‌های پروژه Carthage را تعریف می‌کند. Cartfile در ریشه پروژه در کنار .xcodeproj قرار دارد. هر خط Cartfile یک وابستگی را توصیف می‌کند: منبع (URL Git، مخزن GitHub) و نسخه. نحو از تثبیت نسخه‌ها از طریق tagها، commitها و branchها پشتیبانی می‌کند.

# وابستگی‌های پایه Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

دستور github "Owner/Repo" — فرم کوتاه شده برای مخازن GitHub. Carthage به طور خودکار URL را به شکل https://github.com/Owner/Repo.git می‌سازد. برای GitLab، Bitbucket و سایر میزبان‌های Git از URL کامل استفاده می‌شود: git "https://gitlab.com/owner/repo.git". عملگرهای نسخه: ~> ۵٫۹ (هر نسخه از ۵٫۹ تا ۶٫۰ به استثنای ۶٫۰)، == ۸٫۰٫۰ (نسخه دقیق)، >= ۱٫۰ (حداقل نسخه). اتصال یک commit خاص از طریق github "owner/repo" "abc1234" امکان‌پذیر است.

مثال کامل Cartfile

Carthage از چندین دایرکتوری برای پیکربندی‌های مختلف پشتیبانی می‌کند: Cartfile(اصلی)، Cartfile.private (برای وابستگی‌های داخلی که منتشر نمی‌شوند) و Cartfile.resolved (به طور خودکار تولید می‌شود). وابستگی‌های خصوصی برای کتابخانه‌هایی مفید هستند که فقط در ساخت Development استفاده می‌شوند، مثلاً فریمورک‌های تست.

# Cartfile — وابستگی‌های اصلی
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# آدرس کامل URL برای GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# شاخه توسعه
github "marmelroy/PhoneNumberKit" "development"

github و git — دو نوع منبع در Cartfile. اولی منحصراً برای GitHub در نظر گرفته شده و به طور خودکار URL را تشکیل می‌دهد. دومی — برای هر مخزن Git عمومی یا خصوصی با URL کامل. نسخه می‌تواند با tag (== ۲٫۱٫۱)، محدوده معنایی (~> ۵٫۹)، نام branch ("development") یا هش commit ("a1b2c3d") مشخص شود. استفاده از محدوده‌های معنایی (~>) برای وابستگی‌هایی که از SemVer پیروی می‌کنند توصیه می‌شود — این از تغییرات مخرب در هنگام به‌روزرسانی محافظت می‌کند.

Cartfile.resolved به طور خودکار پس از carthage update تولید می‌شود. این فایل نسخه‌های دقیق تمام وابستگی‌های نصب شده، از جمله وابستگی‌های انتقالی را ثابت می‌کند. فایل باید در Git نگهداری شود — بدون آن دستور carthage bootstrap روی ماشین دیگر کتابخانه‌ها را با همان قوانین می‌سازد، اما نسخه‌ها ممکن است متفاوت باشند. carthage outdated لیست وابستگی‌های قدیمی را نشان می‌دهد که نسخه‌های جدید برای آنها در دسترس است.

نصب و راه‌اندازی Carthage

Carthage از طریق Homebrew — مدیر بسته استاندارد macOS — نصب می‌شود. روش‌های جایگزین: نصب از نصب‌کننده .pkg آماده از GitHub یا ساخت از کد منبع. Carthage به Xcode با Command Line Tools (شامل xcodebuild) نیاز دارد، و در Apple Silicon Mac ممکن است Rosetta 2 برای برخی وابستگی‌های قدیمی‌تر لازم باشد.

# نصب Carthage از طریق Homebrew
brew install carthage

# بررسی نسخه
carthage version

# نصب از .pkg (اگر Homebrew در دسترس نباشد)
# دانلود Carthage.pkg از GitHub Releases و نصب دستی

پس از نصب، راه‌اندازی پروژه Carthage با ایجاد Cartfile در ریشه پروژه آغاز می‌شود. Carthage دستور init ندارد — فایل به صورت دستی در ویرایشگر متن ایجاد می‌شود. پس از پر کردن Cartfile با وابستگی‌ها، توسعه‌دهنده carthage bootstrap (اگر Cartfile.resolved از قبل وجود دارد) یا carthage update (نصب اولیه یا به‌روزرسانی) را اجرا می‌کند. Carthage مخازن را کلون می‌کند، فریمورک‌ها را می‌سازد و آنها را در Carthage/Build/ قرار می‌دهد.

به‌روزرسانی Carthage از طریق brew upgrade carthage انجام می‌شود. نسخه با دستور carthage version بررسی می‌شود. آخرین نسخه پایدار در اواسط ۲۰۲۵ — ۰٫۴۰ با پشتیبانی پیش‌فرض از .xcframework، ساخت موازی بهبود یافته و پشتیبانی کامل از Swift 6. از نسخه ۰٫۳۹ Carthage ساخت .framework قدیمی بدون پل سازگاری را متوقف کرد — توصیه می‌شود به صراحت --use-xcframeworks مشخص شود.

# به‌روزرسانی Carthage از طریق Homebrew
brew upgrade carthage

# نصب نسخه مشخص
brew install carthage@0.39

# نصب مجدد کامل
brew uninstall carthage && brew install carthage

توجه: Carthage .xcworkspace ایجاد نمی‌کند و .xcodeproj را تغییر نمی‌دهد. برخلاف CocoaPods، Carthage کنترل کامل پیکربندی Xcode را به توسعه‌دهنده واگذار می‌کند. این بدان معناست که پس از نصب وابستگی‌ها باید فریمورک‌ها را به صورت دستی در Xcode اضافه کنید (بخش «ادغام فریمورک‌های Carthage در Xcode» را ببینید). Carthage همچنین نیاز دارد که هر وابستگی شامل یک پروژه Xcode یا workspace با target فریمورک باشد — در غیر این صورت ساخت با خطا پایان می‌یابد.

ساخت فریمورک‌ها: bootstrap و update

Carthage سه دستور اصلی برای کار با وابستگی‌ها ارائه می‌دهد: bootstrap، update و build. carthage bootstrap وابستگی‌ها را از Cartfile.resolved موجود می‌سازد — برای محیط‌های CI و توسعه‌دهندگانی که به پروژه ملحق می‌شوند توصیه می‌شود. carthage update Cartfile.resolved را به آخرین نسخه‌ها (با در نظر گرفتن محدودیت‌های Cartfile) به‌روزرسانی کرده و ساخت را انجام می‌دهد. carthage build تمام وابستگی‌های مشخص شده را بدون تثبیت نسخه‌ها می‌سازد.

# نصب اولیه (نسخه‌ها را به‌روزرسانی می‌کند)
carthage update --use-xcframeworks --platform iOS

# ساخت مجدد بر اساس نسخه‌های ثابت
carthage bootstrap --use-xcframeworks --platform iOS

# ساخت فقط یک وابستگی
carthage build Alamofire --platform iOS

فلگ --use-xcframeworks به Carthage دستور می‌دهد به جای .framework قدیمی، .xcframework جهانی بسازد. این پشتیبانی از هر دو شبیه‌ساز و دستگاه واقعی، و همچنین Apple Silicon Mac را بدون اسکریپت‌های اضافی تضمین می‌کند. فلگ --platform iOS ساخت را به یک پلتفرم iOS محدود می‌کند — این به طور قابل توجهی فرآیند را سرعت می‌بخشد، به خصوص اگر کتابخانه‌های چند پلتفرمی در پروژه مشخص شده باشند.

Carthage از ساخت موازی از طریق فلگ --cache-builds پشتیبانی می‌کند که فریمورک‌های ساخته شده را کش می‌کند. در ساخت مجدد، Carthage هش commit Git را بررسی می‌کند و اگر کد تغییر نکرده باشد، کامپایل را رد می‌کند. برای سرورهای CI توصیه می‌شود دایرکتوری Carthage/Build/ و ~/Library/Caches/carthage/ را کش کنید. Carthage همچنین --verbose را برای لاگ‌گیری دقیق و --no-use-binaries را برای ساخت اجباری از کد منبع پشتیبانی می‌کند (اگر توسعه‌دهنده به باینری‌های از پیش ساخته شده اعتماد نداشته باشد).

ادغام فریمورک‌های Carthage در Xcode

ادغام فریمورک‌های Carthage در Xcode به صورت دستی در چهار مرحله انجام می‌شود. پس از اجرای carthage update یا bootstrap تمام فریمورک‌های ساخته شده در Carthage/Build/iOS/ (یا پلتفرم مربوطه) قرار دارند. توسعه‌دهنده پروژه Xcode را باز می‌کند، target برنامه را انتخاب کرده و فریمورک‌ها را در General → Frameworks, Libraries, and Embedded Content اضافه می‌کند. برای فریمورک‌های زمان اجرا (کتابخانه‌های پویا) باید «Embed & Sign» انتخاب شود — در غیر این صورت برنامه هنگام راه‌اندازی با خطای «dyld: Library not loaded» سقوط می‌کند.

Carthage برای کتابخانه‌های استاتیک ساده‌تر کار می‌کند — آنها به مرحله embed نیاز ندارند، زیرا مستقیماً به فایل اجرایی برنامه لینک می‌شوند. اما Carthage به طور پیش‌فرض فریمورک‌های پویا می‌سازد (به جز کتابخانه‌های استاتیکی که به صراحت پیکربندی شده‌اند). برای پروژه‌هایی که به حداقل رساندن اندازه برنامه مهم است، توصیه می‌شود از لینک‌دهی استاتیک از طریق تنظیمات Xcode استفاده کنید.

مرحله اضافی — افزودن Input Files در Build Phase → Run Script. Carthage برای حذف مصنوعات شبیه‌ساز از فریمورک ساخته شده به اسکریپت نیاز دارد (strip simulator architectures). این اسکریپت برای ساخت‌های App Store ضروری است:

# Run Script برای App Store (strip simulator architectures)
FRAMEWORKS_DIR="${SRCROOT}/Carthage/Build/iOS"
for framework in "$FRAMEWORKS_DIR"/*.framework; do
  bash "$BUILD_DIR/src/scripts/strip-framework.sh" "$framework"
done

Carthage به استفاده از .xcworkspace نیاز ندارد — تمام وابستگی‌ها قبلاً به فریمورک‌های باینری ساخته شده‌اند. Carthage مستقیماً با .xcodeproj کار می‌کند، برخلاف CocoaPods که workspace ایجاد می‌کند. این کنترل نسخه و پیکربندی CI را ساده می‌کند، زیرا وابستگی‌های Carthage پیکربندی پروژه Xcode را تغییر نمی‌دهند. تنها تغییر — افزودن فریمورک‌ها به target است که در .pbxproj ثبت می‌شود.

Carthage vs CocoaPods vs Swift Package Manager

Carthage، CocoaPods و Swift Package Manager (SPM) — سه مدیر وابستگی اصلی در توسعه iOS هستند. Carthage با رویکرد غیرمتمرکز متمایز می‌شود، CocoaPods یک رجیستری متمرکز ارائه می‌دهد، SPM — راه‌حل تعبیه شده از Apple. انتخاب بین آنها به نیازهای پروژه، اندازه تیم و سطح اتوماسیون مورد نیاز بستگی دارد.

Carthage برای پروژه‌هایی انتخاب می‌شود که نیاز به حداقل دخالت در پیکربندی Xcode و کنترل کامل بر فرآیند ادغام دارند. Carthage برای کتابخانه‌ها و فریمورک‌های باز ایده‌آل است، جایی که نویسنده می‌خواهد به کاربران امکان ساخت مستقل وابستگی‌ها را بدهد. Carthage همچنین در جامعه توسعه‌دهندگانی که فلسفه UNIX را ارزش می‌نهند محبوب است: هر ابزار یک کار را خوب انجام می‌دهد. CocoaPods استانداردی برای پروژه‌های سازمانی با ده‌ها وابستگی باقی می‌ماند که در آن اتوماسیون مهم است. SPM — انتخابی برای پروژه‌های جدید، زیرا در Xcode تعبیه شده و به طور فعال توسط Apple توسعه می‌یابد.

مهاجرت بین مدیران نیاز به رویکرد متفاوت دارد. Carthage → SPM: فریمورک‌ها را از Xcode حذف کنید، Cartfile را حذف کرده و Package Dependencies را از طریق File → Add Package Dependencies اضافه کنید. Carthage → CocoaPods: فریمورک‌های Carthage را حذف کنید، Podfile ایجاد کنید، وابستگی‌ها را اضافه کرده و pod init && pod install را اجرا کنید. در مهاجرت از Carthage به CocoaPods یا SPM نیاز به به‌روزرسانی دستی فریمورک‌ها از بین می‌رود — تمام وابستگی‌ها با یک دستور به‌روزرسانی می‌شوند. Carthage برای پروژه‌هایی که در آنها اجتناب از vendor lock-in و حفظ شفافیت ساخت وابستگی‌ها مهم است، مرتبط باقی می‌ماند.

مشکلات رایج و رفع آنها

Carthage — ابزاری پایدار است، اما توسعه‌دهندگان گهگاه با مشکلات معمولی مواجه می‌شوند، به ویژه هنگام ساخت روی سرورهای CI، به‌روزرسانی Xcode یا تغییر نسخه‌های Swift. بیشتر مشکلات با پاک کردن کش، پیکربندی صحیح --use-xcframeworks و بررسی تطابق حداقل نسخه iOS حل می‌شود.

خطای «The file manager returned an error» — در هنگام خرابی کش Carthage یا تضاد حقوق فایل رخ می‌دهد. راه‌حل: کش را با دستور rm -rf ~/Library/Caches/carthage حذف کرده و carthage bootstrap را دوباره اجرا کنید. همچنین حذف دایرکتوری Carthage/ در پروژه و ساخت مجدد کمک می‌کند. در سرورهای CI، کش Carthage فقط باید هنگام تغییر Cartfile.resolved به‌روزرسانی شود.

خطای «No such module» — فریمورک در Xcode پیدا نشد، اگرچه ساخت Carthage با موفقیت انجام شد. راه‌حل: مسیر فریمورک را در General → Frameworks, Libraries, and Embedded Content بررسی کنید. فریمورک باید در Carthage/Build/iOS/ باشد. مطمئن شوید .xcframework به درستی اضافه شده است (دوباره بکشید). برای فریمورک‌های پویا Embed & Sign را بررسی کنید. اگر خطا ادامه یافت — FRAMEWORK_SEARCH_PATHS را در Build Settings اضافه کنید.

خطای ساخت به دلیل ناسازگاری Swift — کتابخانه برای نسخه دیگری از Swift نسبت به پروژه ساخته شده است. راه‌حل: از carthage update --no-use-binaries برای ساخت اجباری از کد منبع با همان نسخه Swift استفاده کنید. اگر کتابخانه تحت نسخه فعلی کامپایل نمی‌شود — از .xcconfig برای تعیین نسخه Swift استفاده کنید یا کتابخانه را fork کنید. از Carthage ۰٫۳۹، --use-xcframeworks به طور خودکار نسخه صحیح Swift را در باینری قرار می‌دهد.

مشکلات ساخت CI — Carthage در CI به پیکربندی صحیح کش نیاز دارد. راه‌حل: Carthage/Build/ و ~/Library/Caches/carthage/ را کش کنید. در CI به جای update از carthage bootstrap --use-xcframeworks --platform iOS استفاده کنید تا نسخه‌ها تغییر نکنند. برای GitHub Actions یک action رسمی Carthage موجود است. برای Jenkins — پلاگین CarthageBuild. Carthage ممکن است در macOS بدون GUI سقوط کند — راه‌حل: brew install xcode-build-server را نصب کنید یا کلید -UseModernBuildSystem=NO را اضافه کنید.