Carthage: co to je, decentralizovaný správce závislostí

Co je Carthage?

Carthage — správce závislostí s decentralizovanou architekturou, vytvořený v roce 2014 vývojáři z komunity Swift. Carthage nepoužívá centrální registr specifikací — každá knihovna se připojuje přímo z Git repozitáře pomocí URL nebo názvu na GitHubu. Carthage stahuje zdrojový kód, sestavuje jej do binárního frameworku (.xcframework nebo .framework) a poskytuje vývojáři hotový artefakt k ruční integraci do projektu Xcode.

Architektura Carthage zahrnuje tři komponenty: CLI nástroj carthage, konfigurační soubor Cartfile a adresář Carthage/Build/ se sestavenými frameworky. Principiální rozdíl Carthage oproti CocoaPods — absence automatické modifikace .xcodeproj. Carthage nevytváří .xcworkspace, nenastavuje příznaky kompilátoru a negeneruje Pods.xcconfig. Vývojář přidává frameworky do projektu ručně přes Xcode, což poskytuje plnou kontrolu nad procesem integrace.

Carthage používá paralelní sestavování závislostí, což výrazně urychluje proces na vícejádrových procesorech. Každá závislost je sestavena jako samostatný cíl a Carthage automaticky řeší graf tranzitivních závislostí a sestavuje je ve správném pořadí. Podle benchmarků komunity sestavuje Carthage 15–20 závislostí v průměru za 30–60 sekund na moderních Macích, což je rychlejší než CocoaPods pro projekty s velkým počtem knihoven. Carthage podporuje všechny platformy Apple: iOS, macOS, watchOS a tvOS a od verze 0.38+ — sestavování univerzálních .xcframework pro podporu simulátorů a zařízení Apple Silicon.

Jak Carthage funguje

Carthage klonuje Git repozitář každé závislosti, přepne se na zadanou verzi (tag, commit nebo větev) a spustí xcodebuild pro sestavení frameworku. Carthage určuje typ projektu Xcode (framework, dynamic framework, statická knihovna) automaticky podle schématu sestavení. Pokud projekt obsahuje více schémat, Carthage použije výchozí schéma (první v abecedním pořadí). Po sestavení Carthage zkopíruje hotový framework do Carthage/Build/ a vytvoří soubor Cartfile.resolved s fixací přesných verzí. Carthage podporuje ukládání sestavených frameworků do mezipaměti — opětovné sestavení bez změn závislostí se neprovádí.

Tranzitivní závislosti v Carthage jsou zpracovávány přes Cartfile.resolved: Carthage vytvoří graf všech potřebných závislostí a sestaví je ve správném pořadí. Pokud dvě knihovny závisí na stejné knihovně třetí strany, Carthage ji sestaví jednou a použije pro obě. Carthage oznamuje chyby sestavení s uvedením konkrétního cíle a příčiny — to zjednodušuje diagnostiku problémů.

Cartfile: struktura, syntaxe a příklady

Cartfile — konfigurační soubor v jazyce Ruby (formát Cartfile), který definuje závislosti projektu Carthage. Cartfile se nachází v kořenu projektu vedle .xcodeproj. Každý řádek Cartfile popisuje jednu závislost: zdroj (Git-URL, GitHub repozitář) a verzi. Syntaxe podporuje fixaci verzí pomocí tagů, commitů a větví.

# Základní závislosti Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Direktiva github "Owner/Repo" — zkrácená forma pro GitHub repozitáře. Carthage automaticky vytvoří URL ve tvaru https://github.com/Owner/Repo.git. Pro GitLab, Bitbucket a další Git hostitele se používá plné URL: git "https://gitlab.com/owner/repo.git". Operátory verzí: ~> 5.9 (libovolná verze od 5.9 do 6.0 s výjimkou 6.0), == 8.0.0 (přesná verze), >= 1.0 (minimální verze). Připojení konkrétního commitu lze provést přes github "owner/repo" "abc1234".

Úplný příklad Cartfile

Carthage podporuje několik adresářů pro různé konfigurace: Cartfile(hlavní), Cartfile.private (pro interní závislosti, které se nezveřejňují) a Cartfile.resolved (generuje se automaticky). Soukromé závislosti jsou užitečné pro knihovny používané pouze v Development sestavení, například testovací frameworky.

# Cartfile — základní závislosti
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# Úplná URL pro GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Vývojová větev
github "marmelroy/PhoneNumberKit" "development"

github a git — dva typy zdrojů v Cartfile. První je určen výhradně pro GitHub a automaticky vytváří URL. Druhý — pro libovolné veřejné nebo soukromé Git repozitáře s plným URL. Verze může být specifikována tagem (== 2.1.1), sémantickým rozsahem (~> 5.9), názvem větve ("development") nebo hash commitu ("a1b2c3d"). Použití sémantických rozsahů (~>) se doporučuje pro závislosti, které dodržují SemVer — chrání to před breaking changes při aktualizaci.

Cartfile.resolved se generuje automaticky po carthage update. Fixuje přesné verze všech nainstalovaných závislostí, včetně tranzitivních. Soubor by měl být uchováván v Git — bez něj příkaz carthage bootstrap na jiném počítači sestaví knihovny podle stejných pravidel, ale verze se mohou lišit. carthage outdated zobrazuje seznam zastaralých závislostí, pro které jsou k dispozici nové verze.

Instalace a konfigurace Carthage

Carthage se instaluje přes Homebrew — standardního správce balíčků pro macOS. Alternativní způsoby: instalace z hotového .pkg instalátoru z GitHubu nebo sestavení ze zdrojového kódu. Carthage vyžaduje Xcode s Command Line Tools (včetně xcodebuild), a na Apple Silicon Mac — Rosetta 2 pro některé starší závislosti.

# Instalace Carthage přes Homebrew
brew install carthage

# Kontrola verze
carthage version

# Instalace z .pkg (pokud Homebrew není k dispozici)
# Stáhnout Carthage.pkg z GitHub Releases a nainstalovat ručně

Po instalaci začíná inicializace projektu Carthage vytvořením Cartfile v kořenu projektu. Carthage nemá příkaz init — soubor se vytváří ručně v textovém editoru. Po naplnění Cartfile závislostmi vývojář spustí carthage bootstrap (pokud Cartfile.resolved již existuje) nebo carthage update (první instalace nebo aktualizace). Carthage klonuje repozitáře, sestavuje frameworky a umísťuje je do Carthage/Build/.

Aktualizace Carthage se provádí přes brew upgrade carthage. Verze se kontroluje příkazem carthage version. Poslední stabilní verze v polovině 2025 — 0.40 s výchozí podporou .xcframework, vylepšeným paralelním sestavováním a plnou podporou Swift 6. Od verze 0.39 Carthage přestal sestavovat zastaralé .framework bez kompatibilního mostu — doporučuje se explicitně uvádět --use-xcframeworks.

# Aktualizace Carthage přes Homebrew
brew upgrade carthage

# Instalace konkrétní verze
brew install carthage@0.39

# Úplná přeinstalace
brew uninstall carthage && brew install carthage

Poznámka: Carthage nevytváří .xcworkspace a nemodifikuje .xcodeproj. Na rozdíl od CocoaPods, Carthage ponechává plnou kontrolu nad konfigurací Xcode vývojáři. To znamená, že po instalaci závislostí je třeba ručně přidat frameworky do Xcode (viz sekce «Integrace Carthage frameworků do Xcode»). Carthage také vyžaduje, aby každá závislost obsahovala projekt Xcode nebo workspace s cílem frameworku — jinak sestavení skončí chybou.

Sestavování frameworků: bootstrap a update

Carthage nabízí tři hlavní příkazy pro práci se závislostmi: bootstrap, update a build. carthage bootstrap sestavuje závislosti z existujícího Cartfile.resolved — doporučeno pro CI prostředí a vývojáře připojující se k projektu. carthage update aktualizuje Cartfile.resolved na nejnovější verze (s ohledem na omezení Cartfile) a provádí sestavení. carthage build sestavuje všechny zadané závislosti bez ukládání verzí.

# První instalace (aktualizuje verze)
carthage update --use-xcframeworks --platform iOS

# Opětovné sestavení podle pevných verzí
carthage bootstrap --use-xcframeworks --platform iOS

# Sestavení pouze jedné závislosti
carthage build Alamofire --platform iOS

Příznak --use-xcframeworks dává Carthage pokyn sestavovat univerzální .xcframework místo zastaralých .framework. To zajišťuje podporu jak simulátoru, tak skutečného zařízení, stejně jako Apple Silicon Mac bez dalších skriptů. Příznak --platform iOS omezuje sestavení na jednu platformu iOS — to výrazně urychluje proces, zejména pokud projekt obsahuje multiplatformní knihovny.

Carthage podporuje paralelní sestavování přes příznak --cache-builds, který ukládá do mezipaměti již sestavené frameworky. Při opětovném sestavení Carthage kontroluje hash commitu Git a pokud se kód nezměnil, kompilaci přeskočí. Pro CI servery se doporučuje ukládat do mezipaměti adresář Carthage/Build/ a ~/Library/Caches/carthage/. Carthage také podporuje --verbose pro podrobné logování a --no-use-binaries pro vynucené sestavení ze zdrojového kódu (pokud vývojář nedůvěřuje předpřipraveným binárkám).

Integrace Carthage frameworků do Xcode

Integrace Carthage frameworků do Xcode se provádí ručně ve čtyřech krocích. Po provedení carthage update nebo bootstrap jsou všechny sestavené frameworky v Carthage/Build/iOS/ (nebo příslušné platformě). Vývojář otevře projekt Xcode, vybere cíl aplikace a přidá frameworky do General → Frameworks, Libraries, and Embedded Content. Pro runtime frameworky (dynamické knihovny) je třeba vybrat «Embed & Sign» — jinak aplikace spadne při spuštění s chybou «dyld: Library not loaded».

Carthage pro statické knihovny funguje jednodušeji — nevyžadují fázi embed, protože se linkují přímo do spustitelného souboru aplikace. Carthage však ve výchozím nastavení sestavuje dynamické frameworky (kromě explicitně nakonfigurovaných statických knihoven). Pro projekty, kde je důležité minimalizovat velikost aplikace, se doporučuje používat statické linkování přes nastavení Xcode.

Další krok — přidání Input Files do Build Phase → Run Script. Carthage vyžaduje skript pro odstranění artefaktů simulátoru ze sestaveného frameworku (strip simulator architectures). Tento skript je nezbytný pro sestavení pro App Store:

# Run Script pro 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 nevyžaduje použití .xcworkspace — všechny závislosti jsou již sestaveny do binárních frameworků. Carthage pracuje přímo s .xcodeproj, na rozdíl od CocoaPods, který vytváří workspace. To zjednodušuje správu verzí a konfiguraci CI, protože závislosti Carthage nemění konfiguraci projektu Xcode. Jedinou změnou je přidání frameworků do cíle, které je zaznamenáno v .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods a Swift Package Manager (SPM) — tři hlavní správci závislostí ve vývoji pro iOS. Carthage se vyznačuje decentralizovaným přístupem, CocoaPods nabízí centralizovaný registr, SPM — vestavěné řešení od Apple. Volba mezi nimi závisí na požadavcích projektu, velikosti týmu a požadované úrovni automatizace.

Carthage se volí pro projekty, kde je vyžadován minimální zásah do konfigurace Xcode a plná kontrola nad procesem integrace. Carthage je ideální pro otevřené knihovny a frameworky, kde autor chce dát uživatelům možnost sestavovat závislosti samostatně. Carthage je také populární v komunitě vývojářů, kteří oceňují UNIX filozofii: každý nástroj dělá jednu věc dobře. CocoaPods zůstává standardem pro podnikové projekty s desítkami závislostí, kde je důležitá automatizace. SPM — volba pro nové projekty, protože je integrován v Xcode a aktivně vyvíjen Apple.

Migrace mezi správci vyžaduje různý přístup. Carthage → SPM: odstraňte frameworky z Xcode, smažte Cartfile a přidejte Package Dependencies přes File → Add Package Dependencies. Carthage → CocoaPods: odstraňte Carthage frameworky, vytvořte Podfile, přidejte závislosti a spusťte pod init && pod install. Při migraci z Carthage na CocoaPods nebo SPM mizí potřeba ručně aktualizovat frameworky — všechny závislosti se aktualizují jedním příkazem. Carthage zůstává relevantní pro projekty, kde je důležité vyhnout se vendor lock-in a zachovat transparentnost sestavování závislostí.

Běžné problémy a jejich řešení

Carthage — stabilní nástroj, ale vývojáři občas narazí na typické problémy, zejména při sestavování na CI serverech, aktualizaci Xcode nebo změně verzí Swift. Většina problémů se řeší vyčištěním mezipaměti, správnou konfigurací --use-xcframeworks a kontrolou souladu s minimální verzí iOS.

Chyba «The file manager returned an error» — vzniká při poškození mezipaměti Carthage nebo konfliktu přístupových práv k souborům. Řešení: odstraňte mezipaměť příkazem rm -rf ~/Library/Caches/carthage a znovu spusťte carthage bootstrap. Pomáhá také odstranění adresáře Carthage/ v projektu a opětovné sestavení. Na CI serverech by se mezipaměť Carthage měla aktualizovat pouze při změně Cartfile.resolved.

Chyba «No such module» — framework nebyl nalezen v Xcode, přestože sestavení Carthage bylo úspěšné. Řešení: zkontrolujte cestu frameworku v General → Frameworks, Libraries, and Embedded Content. Framework by měl být v Carthage/Build/iOS/. Ujistěte se, že .xcframework byl přidán správně (přetáhněte znovu). Pro dynamické frameworky zkontrolujte Embed & Sign. Pokud chyba přetrvává — přidejte FRAMEWORK_SEARCH_PATHS do Build Settings.

Chyba při sestavení kvůli nekompatibilitě Swift — knihovna je sestavena pro jinou verzi Swift než projekt. Řešení: použijte carthage update --no-use-binaries pro vynucené sestavení ze zdrojového kódu stejnou verzí Swift. Pokud se knihovna nezkompiluje pod aktuální verzí — použijte .xcconfig pro uvedení verze Swift nebo forkujte knihovnu. Od Carthage 0.39, --use-xcframeworks automaticky zahrnuje správnou verzi Swift do binárky.

Problémy s CI sestavením — Carthage na CI vyžaduje správnou konfiguraci ukládání do mezipaměti. Řešení: ukládejte do mezipaměti Carthage/Build/ a ~/Library/Caches/carthage/. Používejte carthage bootstrap --use-xcframeworks --platform iOS místo update na CI, abyste neměnili verze. Pro GitHub Actions je k dispozici oficiální Carthage akce. Pro Jenkins — plugin CarthageBuild. Carthage může spadnout na macOS bez GUI — řešení: nainstalujte brew install xcode-build-server nebo přidejte klíč -UseModernBuildSystem=NO.