Carthage: bu nədir, mərkəzləşdirilməmiş asılılıq meneceri

Carthage nədir?

Carthage — 2014-cü ildə Swift icmasının tərtibatçıları tərəfindən yaradılmış mərkəzləşdirilməmiş arxitekturaya malik asılılıq meneceridir. Carthage mərkəzi spesifikasiya reyestrindən istifadə etmir — hər bir kitabxana birbaşa Git repozitoriyasından URL və ya GitHub adı ilə qoşulur. Carthage mənbə kodunu yükləyir, onu ikili freymvorka (.xcframework və ya .framework) qurur və tərtibatçıya Xcode layihəsinə əl ilə inteqrasiya üçün hazır artefakt təqdim edir.

Carthage arxitekturası üç komponentdən ibarətdir: carthage CLI aləti, Cartfile konfiqurasiya faylı və qurulmuş freymvorkları olan Carthage/Build/ kataloqu. Carthage-in CocoaPods-dan prinsipial fərqi — .xcodeproj-un avtomatik dəyişdirilməməsidir. Carthage .xcworkspace yaratmır, kompilyator flaglarını konfiqurasiya etmir və Pods.xcconfig yaratmır. Tərtibatçı freymvorkları Xcode vasitəsilə layihəyə özü əlavə edir ki, bu da inteqrasiya prosesi üzərində tam nəzarət verir.

Carthage asılılıqların paralel qurulmasından istifadə edir ki, bu da çoxnüvəli prosessorlarda prosesi əhəmiyyətli dərəcədə sürətləndirir. Hər bir asılılıq ayrıca target kimi qurulur və Carthage transiv asılılıqlar qrafikini avtomatik həll edərək onları düzgün ardıcıllıqla qurur. İcma benchmarklarına görə, Carthage 15–20 asılılığı müasir Mac-larda orta hesabla 30–60 saniyəyə qurur ki, bu da çox sayda kitabxanası olan layihələr üçün CocoaPods-dan daha sürətlidir. Carthage bütün Apple platformalarını dəstəkləyir: iOS, macOS, watchOS və tvOS, 0.38+ versiyasından isə simulyatorların və Apple Silicon cihazlarının dəstəyi üçün universal .xcframework qurulmasını dəstəkləyir.

Carthage necə işləyir

Carthage hər bir asılılığın Git repozitoriyasını klonlayır, göstərilən versiyaya (tag, commit və ya branch) keçir və freymvorku qurmaq üçün xcodebuild-i işə salır. Carthage Xcode layihəsinin növünü (freymvork, dynamic freymvork, statik kitabxana) quruluş sxemi üzrə avtomatik müəyyən edir. Layihədə bir neçə sxem varsa, Carthage standart sxemdən (əlifba sırasında birinci) istifadə edir. Qurulmadan sonra Carthage hazır freymvorku Carthage/Build/-ə kopyalayır və dəqiq versiyaları təsbit edən Cartfile.resolved faylını yaradır. Carthage qurulmuş freymvorkların keşlənməsini dəstəkləyir — asılılıqlar dəyişməyibsə, təkrar qurulma yerinə yetirilmir.

Carthage-də transiv asılılıqlar Cartfile.resolved vasitəsilə idarə olunur: Carthage bütün lazımi asılılıqların qrafikini qurur və onları düzgün ardıcıllıqla yığır. Əgər iki kitabxana eyni üçüncü tərəf kitabxanasından asılıdırsa, Carthage onu bir dəfə qurur və hər ikisi üçün istifadə edir. Carthage qurulma xətalarını konkret target və səbəbi göstərərək bildirir — bu, problemlərin diaqnostikasını asanlaşdırır.

Cartfile: strukturu, sintaksisi və nümunələri

Cartfile — Ruby dilində (Cartfile formatı) Carthage layihəsinin asılılıqlarını təyin edən konfiqurasiya faylıdır. Cartfile layihənin kökündə .xcodeproj-un yanında yerləşir. Cartfile-in hər sətri bir asılılığı təsvir edir: mənbə (Git-URL, GitHub repozitoriyası) və versiya. Sintaksis versiyaların taglar, commitlər və branch-lar vasitəsilə təsbitini dəstəkləyir.

# Əsas asılılıqlar Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

github "Owner/Repo" direktivi — GitHub repozitoriyaları üçün qısaldılmış formadır. Carthage avtomatik olaraq https://github.com/Owner/Repo.git şəklində URL yaradır. GitLab, Bitbucket və digər Git hostinqləri üçün tam URL istifadə olunur: git "https://gitlab.com/owner/repo.git". Versiya operatorları: ~> 5.9 (5.9-dan 6.0-dək istənilən versiya, 6.0 xaric), == 8.0.0 (dəqiq versiya), >= 1.0 (minimum versiya). Konkret commit-i github "owner/repo" "abc1234" vasitəsilə qoşmaq olar.

Cartfile-in tam nümunəsi

Carthage müxtəlif konfiqurasiyalar üçün bir neçə kataloqu dəstəkləyir: Cartfile (əsas), Cartfile.private (dərc olunmayan daxili asılılıqlar üçün) və Cartfile.resolved (avtomatik yaradılır). Şəxsi asılılıqlar yalnız Development qurulmasında istifadə olunan kitabxanalar, məsələn test freymvorkları üçün faydalıdır.

# Cartfile — əsas asılılıqlar
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# Tam URL üçün GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# İnkişaf branch-ı
github "marmelroy/PhoneNumberKit" "development"

github və git — Cartfile-də iki növ mənbədir. Birincisi yalnız GitHub üçün nəzərdə tutulub və avtomatik URL yaradır. İkincisi — tam URL ilə istənilən açıq və ya özəl Git repozitoriyaları üçün. Versiya tag (== 2.1.1), semantik diapazon (~> 5.9), branch adı ("development") və ya commit hash-i ("a1b2c3d") ilə göstərilə bilər. Semantik diapazonların (~>) istifadəsi SemVer-ə əməl edən asılılıqlar üçün tövsiyə olunur — bu, yeniləmə zamanı pozucu dəyişikliklərdən qoruyur.

Cartfile.resolved carthage update-dən sonra avtomatik yaradılır. O, bütün quraşdırılmış asılılıqların, o cümlədən transiv olanların dəqiq versiyalarını təsbit edir. Fayl Git-də saxlanmalıdır — onsuz başqa maşında carthage bootstrap əmri kitabxanaları eyni qaydalarla quracaq, lakin versiyalar fərqlənə bilər. carthage outdated yeni versiyaları mövcud olan köhnəlmiş asılılıqların siyahısını göstərir.

Carthage-in quraşdırılması və konfiqurasiyası

Carthage Homebrew — macOS üçün standart paket meneceri vasitəsilə quraşdırılır. Alternativ üsullar: GitHub-dan hazır .pkg quraşdırıcısından quraşdırma və ya mənbə kodundan qurma. Carthage Xcode Command Line Tools (xcodebuild daxil olmaqla) tələb edir, Apple Silicon Mac-da isə bəzi köhnə asılılıqlar üçün Rosetta 2 tələb oluna bilər.

# Quraşdırma Carthage vasitəsilə Homebrew
brew install carthage

# Versiyanın yoxlanılması
carthage version

# .pkg-dən quraşdırma (əgər Homebrew əlçatan deyil)
# Endir Carthage.pkg-i GitHub Releases və əl ilə quraşdırın

Quraşdırmadan sonra Carthage layihəsinin inisializasiyası layihənin kökündə Cartfile yaratmaqla başlayır. Carthage init əmrinə malik deyil — fayl mətn redaktorunda əl ilə yaradılır. Cartfile-i asılılıqlarla doldurduqdan sonra tərtibatçı carthage bootstrap (əgər Cartfile.resolved artıq varsa) və ya carthage update (ilkin quraşdırma və ya yeniləmə) işə salır. Carthage repozitoriyaları klonlayır, freymvorkları qurur və onları Carthage/Build/-ə yerləşdirir.

Carthage-in yenilənməsi brew upgrade carthage vasitəsilə həyata keçirilir. Versiya carthage version əmri ilə yoxlanılır. mid-2025-ə olan son stabil versiya — 0.40, standart olaraq .xcframework dəstəyi, təkmilləşdirilmiş paralel qurulma və Swift 6-nın tam dəstəyi ilə. 0.39 versiyasından başlayaraq Carthage uyğunluq qurğusu olmayan köhnəlmiş .framework-ləri qurmağı dayandırdı — --use-xcframeworks-i açıq şəkildə göstərmək tövsiyə olunur.

# Yeniləmə Carthage vasitəsilə Homebrew
brew upgrade carthage

# Müəyyən versiyanın quraşdırılması
brew install carthage@0.39

# Tam yenidən quraşdırma
brew uninstall carthage && brew install carthage

Diqqət: Carthage .xcworkspace yaratmır və .xcodeproj-u dəyişdirmir. CocoaPods-dan fərqli olaraq, Carthage Xcode konfiqurasiyasına tam nəzarəti tərtibatçıya buraxır. Bu o deməkdir ki, asılılıqları quraşdırdıqdan sonra freymvorkları Xcode-da əl ilə əlavə etmək lazımdır (bax «Carthage freymvorklarının Xcode-da inteqrasiyası» bölməsi). Carthage həmçinin hər bir asılılığın freymvork targeti olan Xcode layihəsi və ya workspace-i ehtiva etməsini tələb edir — əks halda qurulma xəta ilə başa çatacaq.

Freymvorkların qurulması: bootstrap və update

Carthage asılılıqlarla işləmək üçün üç əsas əmr təklif edir: bootstrap, update və build. carthage bootstrap mövcud Cartfile.resolved-dən asılılıqları qurur — CI mühitləri və layihəyə qoşulan tərtibatçılar üçün tövsiyə olunur. carthage update Cartfile.resolved-i son versiyalara (Cartfile məhdudiyyətləri nəzərə alınmaqla) yeniləyir və qurulmanı yerinə yetirir. carthage build versiyaları qeyd etmədən bütün göstərilən asılılıqları qurur.

# İlkin quraşdırma (versiyaları yeniləyir)
carthage update --use-xcframeworks --platform iOS

# Təsbit edilmiş versiyalar üzrə təkrar qurulma
carthage bootstrap --use-xcframeworks --platform iOS

# Yalnız bir asılılığın qurulması
carthage build Alamofire --platform iOS

--use-xcframeworks flag-ı Carthage-ə köhnəlmiş .framework əvəzinə universal .xcframework qurmağı göstərir. Bu, həm simulyatorun, həm də real cihazın, həmçinin Apple Silicon Mac-in əlavə skriptlər olmadan dəstəklənməsini təmin edir. --platform iOS flag-ı qurulmanı yalnız iOS platforması ilə məhdudlaşdırır — bu, xüsusilə layihədə çoxplatformalı kitabxanalar göstərilibsə, prosesi əhəmiyyətli dərəcədə sürətləndirir.

Carthage --cache-builds flag-ı vasitəsilə paralel qurulmanı dəstəkləyir, artıq qurulmuş freymvorkları keşləyir. Təkrar qurulmada Carthage Git commit hash-ini yoxlayır və kod dəyişməyibsə, kompilasiyanı buraxır. CI serverləri üçün Carthage/Build/ və ~/Library/Caches/carthage/ kataloqlarının keşlənməsi tövsiyə olunur. Carthage həmçinin ətraflı loglama üçün --verbose və mənbə kodundan məcburi qurulma üçün --no-use-binaries dəstəkləyir (əgər tərtibatçı əvvəlcədən qurulmuş binarlara etibar etmirsə).

Carthage freymvorklarının Xcode-da inteqrasiyası

İnteqrasiya Carthage freymvorklarının Xcode-da əl ilə dörd addımda yerinə yetirilir. carthage update və ya bootstrap yerinə yetirildikdən sonra bütün qurulmuş freymvorklar Carthage/Build/iOS/-də (və ya müvafiq platformada) yerləşir. Tərtibatçı Xcode layihəsini açır, tətbiq targetini seçir və freymvorkları General → Frameworks, Libraries, and Embedded Content bölməsinə əlavə edir. İcra zamanı freymvorklar (dinamik kitabxanalar) üçün «Embed & Sign» seçilməlidir — əks halda tətbiq işə salınarkən «dyld: Library not loaded» xətası ilə çökəcək.

Carthage statik kitabxanalar üçün daha sadə işləyir — onlar embed mərhələsi tələb etmir, çünki birbaşa tətbiqin icra edilə bilən faylına bağlanır. Lakin Carthage standart olaraq dinamik freymvorklar qurur (açıq şəkildə konfiqurasiya edilmiş statik kitabxanalar istisna olmaqla). Tətbiq ölçüsünü minimuma endirmək vacib olan layihələr üçün Xcode parametrləri vasitəsilə statik bağlamadan istifadə etmək tövsiyə olunur.

Əlavə addım — Build Phase → Run Script-də Input Files əlavə etmək. Carthage qurulmuş freymvorkdan simulyator artefaktlarını silmək üçün skript tələb edir (strip simulator architectures). Bu skript App Store qurulmaları üçün zəruridir:

# Run Script üçün 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 istifadəsini tələb etmir — bütün asılılıqlar artıq ikili freymvorklara qurulub. Carthage CocoaPods-dan fərqli olaraq birbaşa .xcodeproj ilə işləyir, workspace yaratmır. Bu, versiya nəzarətini və CI konfiqurasiyasını asanlaşdırır, çünki Carthage asılılıqları Xcode layihəsinin konfiqurasiyasını dəyişdirmir. Yeganə dəyişiklik — .pbxproj-də qeydə alınan freymvorkların target-ə əlavə edilməsidir.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods və Swift Package Manager (SPM) — iOS tərtibatında üç əsas asılılıq meneceridir. Carthage mərkəzləşdirilməmiş yanaşması ilə seçilir, CocoaPods mərkəzləşdirilmiş reyestr təklif edir, SPM — Apple-dan daxili həll. Onlar arasında seçim layihənin tələblərindən, komandanın ölçüsündən və tələb olunan avtomatlaşdırma səviyyəsindən asılıdır.

Carthage Xcode konfiqurasiyasına minimal müdaxilə və inteqrasiya prosesi üzərində tam nəzarət tələb olunan layihələr üçün seçilir. Carthage açıq kitabxanalar və freymvorklar üçün idealdır, burada müəllif istifadəçilərə asılılıqları özləri qurmaq imkanı vermək istəyir. Carthage həmçinin UNIX fəlsəfəsini dəyərləndirən tərtibatçı icmasında populyardır: hər alət bir işi yaxşı yerinə yetirir. CocoaPods, avtomatlaşdırmanın vacib olduğu onlarla asılılığı olan korporativ layihələr üçün standart olaraq qalır. SPM — Xcode-a daxil edildiyi və Apple tərəfindən aktiv şəkildə inkişaf etdirildiyi üçün yeni layihələr üçün seçimdir.

Miqrasiya menecerlər arasında fərqli yanaşma tələb edir. Carthage → SPM: freymvorkları Xcode-dan silin, Cartfile-i silin və File → Add Package Dependencies vasitəsilə Package Dependencies əlavə edin. Carthage → CocoaPods: Carthage freymvorklarını silin, Podfile yaradın, asılılıqları əlavə edin və pod init && pod install yerinə yetirin. Carthage-dən CocoaPods və ya SPM-ə miqrasiya zamanı freymvorkları əl ilə yeniləmək ehtiyacı aradan qalxır — bütün asılılıqlar bir əmrlə yenilənir. Carthage, vendor lock-in-dən qaçmaq və asılılıqların qurulmasının şəffaflığını qorumaq vacib olan layihələr üçün aktual olaraq qalır.

Ümumi problemlər və onların həlli

Carthage — sabit alətdir, lakin tərtibatçılar vaxtaşırı tipik problemlərlə, xüsusilə CI serverlərində qurulma, Xcode-un yenilənməsi və ya Swift versiyalarının dəyişməsi zamanı qarşılaşırlar. Əksər problemlər keşin təmizlənməsi, --use-xcframeworks-in düzgün konfiqurasiyası və minimal iOS versiyasının uyğunluğunun yoxlanılması ilə həll olunur.

«The file manager returned an error» xətası — Carthage keşinin zədələnməsi və ya fayl hüquqları münaqişəsi zamanı yaranır. Həlli: rm -rf ~/Library/Caches/carthage əmri ilə keşi silin və carthage bootstrap-i yenidən işə salın. Layihədə Carthage/ kataloqunu silmək və təkrar qurmaq da kömək edir. CI serverlərində Carthage keşi yalnız Cartfile.resolved dəyişdikdə yenilənməlidir.

«No such module» xətası — freymvork Xcode-da tapılmır, baxmayaraq ki, Carthage qurulması uğurla başa çatıb. Həlli: General → Frameworks, Libraries, and Embedded Content bölməsində freymvork yolunu yoxlayın. Freymvork Carthage/Build/iOS/-də olmalıdır. .xcframework-in düzgün əlavə edildiyinə əmin olun (yenidən sürükləyin). Dinamik freymvorklar üçün Embed & Sign-i yoxlayın. Xəta davam edərsə — Build Settings-də FRAMEWORK_SEARCH_PATHS əlavə edin.

Swift uyğunsuzluğu səbəbindən qurulma xətası — kitabxana layihədən fərqli Swift versiyası üçün qurulub. Həlli: eyni Swift versiyası ilə mənbə kodundan məcburi qurulma üçün carthage update --no-use-binaries istifadə edin. Kitabxana cari versiya altında kompilə olunmursa — Swift versiyasını göstərmək üçün .xcconfig istifadə edin və ya kitabxananı fork edin. Carthage 0.39-dan başlayaraq, --use-xcframeworks avtomatik olaraq düzgün Swift versiyasını binara daxil edir.

CI qurulması problemləri — Carthage CI-də düzgün keş konfiqurasiyası tələb edir. Həlli: Carthage/Build/ və ~/Library/Caches/carthage/-i keşləyin. CI-də versiyaları dəyişməmək üçün update əvəzinə carthage bootstrap --use-xcframeworks --platform iOS istifadə edin. GitHub Actions üçün rəsmi Carthage action mövcuddur. Jenkins üçün — CarthageBuild plugin. Carthage GUI olmayan macOS-da çökə bilər — həlli: brew install xcode-build-server quraşdırın və ya -UseModernBuildSystem=NO açarını əlavə edin.