Carthage: mi ez, decentralizált függőségkezelő

Mi az a Carthage?

Carthage — decentralizált architektúrájú függőségkezelő, amelyet 2014-ben hoztak létre a Swift közösség fejlesztői. A Carthage nem használ központi specifikációs nyilvántartást — minden könyvtár közvetlenül a Git-adattárból csatlakozik URL-en vagy GitHub néven keresztül. A Carthage letölti a forráskódot, bináris keretrendszerré (.xcframework vagy .framework) építi és kész artefaktumot biztosít a fejlesztőnek kézi integrációhoz az Xcode-projektbe.

A Carthage architektúrája három komponensből áll: a carthage CLI-eszközből, a Cartfile konfigurációs fájlból és a Carthage/Build/ könyvtárból az épített keretrendszerekkel. A Carthage alapvető különbsége a CocoaPods-hoz képest — a .xcodeproj automatikus módosításának hiánya. A Carthage nem hoz létre .xcworkspace-et, nem konfigurál fordító jelzőket és nem generál Pods.xcconfig-ot. A fejlesztő maga adja hozzá a keretrendszereket a projekthez az Xcode-on keresztül, ami teljes irányítást biztosít az integrációs folyamat felett.

Carthage párhuzamos függőségépítést használ, ami jelentősen felgyorsítja a folyamatot a többmagos processzorokon. Minden függőség külön célként épül, és a Carthage automatikusan feloldja a tranzitív függőségek gráfját, a megfelelő sorrendben építve azokat. A közösségi mérések szerint a Carthage 15–20 függőséget átlagosan 30–60 másodperc alatt épít fel modern Mac-eken, ami gyorsabb, mint a CocoaPods a sok könyvtárat tartalmazó projekteknél. A Carthage támogatja az összes Apple-platformot: iOS, macOS, watchOS és tvOS, valamint a 0.38+ verziótól — univerzális .xcframework építését a szimulátorok és Apple Silicon eszközök támogatásához.

Hogyan működik a Carthage

Carthage klónozza az egyes függőségek Git-adattárát, átvált a megadott verzióra (tag, commit vagy ág) és elindítja az xcodebuild-et a keretrendszer építéséhez. A Carthage automatikusan meghatározza az Xcode-projekt típusát (keretrendszer, dinamikus keretrendszer, statikus könyvtár) az építési séma alapján. Ha a projekt több sémát tartalmaz, a Carthage az alapértelmezett sémát használja (az elsőt ábécé sorrendben). Az építés után a Carthage a kész keretrendszert a Carthage/Build/-be másolja és létrehozza a Cartfile.resolved fájlt a pontos verziók rögzítésével. A Carthage támogatja az épített keretrendszerek gyorsítótárazását — a függőségek változatlansága esetén az újraépítés nem történik meg.

A tranzitív függőségek a Carthage-ben a Cartfile.resolved-on keresztül történnek: a Carthage felépíti az összes szükséges függőség gráfját és a megfelelő sorrendben építi azokat. Ha két könyvtár ugyanattól a harmadik féltől származó könyvtártól függ, a Carthage azt egyszer építi fel és mindkettőhöz használja. A Carthage értesíti az építési hibákról a konkrét cél és ok megadásával — ez leegyszerűsíti a problémák diagnosztizálását.

Cartfile: struktúra, szintaxis és példák

Cartfile — Ruby nyelvű (Cartfile formátum) konfigurációs fájl, amely meghatározza a Carthage-projekt függőségeit. A Cartfile a projekt gyökerében található a .xcodeproj mellett. A Cartfile minden sora egy függőséget ír le: forrást (Git-URL, GitHub-adattár) és verziót. A szintaxis támogatja a verziók rögzítését tageken, commiteken és ágakon keresztül.

# Alapvető függőségek Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

A github "Owner/Repo" direktíva — rövidített forma GitHub-adattárakhoz. A Carthage automatikusan létrehozza az URL-t https://github.com/Owner/Repo.git formában. A GitLab, Bitbucket és más Git-tárhelyek esetén a teljes URL-t kell használni: git "https://gitlab.com/owner/repo.git". Verzió operátorok: ~> 5.9 (bármely verzió 5.9-től 6.0-ig, a 6.0 kivételével), == 8.0.0 (pontos verzió), >= 1.0 (minimális verzió). Egy adott commit csatlakoztatható a github "owner/repo" "abc1234" segítségével.

Teljes Cartfile példa

Carthage több könyvtárat támogat különböző konfigurációkhoz: Cartfile(fő), Cartfile.private (belső, nem publikált függőségekhez) és Cartfile.resolved (automatikusan generált). A privát függőségek olyan könyvtárakhoz hasznosak, amelyek csak a Development-építésben használatosak, például tesztkeretrendszerek.

# Cartfile — fő függőségek
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# A teljes URL a(z) GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Fejlesztési ág
github "marmelroy/PhoneNumberKit" "development"

github és git — két forrástípus a Cartfile-ban. Az első kizárólag a GitHub-ra szolgál és automatikusan formálja az URL-t. A második — bármely nyilvános vagy privát Git-adattárhoz teljes URL-lel. A verzió megadható tag-gel (== 2.1.1), szemantikus tartománnyal (~> 5.9), ágnévvel ("development") vagy commit hash-sel ("a1b2c3d"). A szemantikus tartományok (~>) használata ajánlott a SemVer-t követő függőségekhez — ez véd a frissítéskor bekövetkező megszakító változásoktól.

Cartfile.resolved automatikusan generálódik a carthage update után. Rögzíti az összes telepített függőség pontos verzióját, beleértve a tranzitívakat is. A fájlt Git-ben kell tartani — enélkül a carthage bootstrap parancs egy másik gépen ugyanazokkal a szabályokkal építi a könyvtárakat, de a verziók eltérhetnek. A carthage outdated megjeleníti az elavult függőségek listáját, amelyekhez új verziók érhetők el.

A Carthage telepítése és konfigurálása

Carthage a Homebrew-n — a macOS szabványos csomagkezelőjén — keresztül telepíthető. Alternatív módszerek: telepítés a kész .pkg telepítőből a GitHub-ról vagy építés forráskódból. A Carthage Xcode-ot igényel Command Line Tools-szal (beleértve az xcodebuild-et), valamint Apple Silicon Mac-en — Rosetta 2-t néhány régebbi függőséghez.

# Telepítés Carthage segítségével Homebrew
brew install carthage

# Verzió ellenőrzése
carthage version

# Telepítés .pkg-ből (ha Homebrew nem elérhető)
# Töltse le a(z) Carthage.pkg fájlt a(z) GitHub Releases oldalról, és telepítse manuálisan

A telepítés után a Carthage-projekt inicializálása a Cartfile létrehozásával kezdődik a projekt gyökerében. A Carthage-nak nincs init parancsa — a fájl kézzel jön létre egy szövegszerkesztőben. A Cartfile függőségekkel való kitöltése után a fejlesztő elindítja a carthage bootstrap-et (ha Cartfile.resolved már létezik) vagy a carthage update-et (első telepítés vagy frissítés). A Carthage klónozza az adattárakat, felépíti a keretrendszereket és elhelyezi azokat a Carthage/Build/-ben.

A Carthage frissítése a brew upgrade carthage segítségével történik. A verzió a carthage version paranccsal ellenőrizhető. A legutolsó stabil verzió 2025 közepén — 0.40 alapértelmezett .xcframework támogatással, javított párhuzamos építéssel és teljes Swift 6 támogatással. A 0.39-es verziótól kezdve a Carthage leállította az elavult .framework-ek építését kompatibilitási híd nélkül — ajánlott explicit módon megadni a --use-xcframeworks-et.

# Frissítés Carthage segítségével Homebrew
brew upgrade carthage

# Adott verzió telepítése
brew install carthage@0.39

# Teljes újratelepítés
brew uninstall carthage && brew install carthage

Megjegyzés: a Carthage nem hoz létre .xcworkspace-et és nem módosítja a .xcodeproj-t. A CocoaPods-szal ellentétben a Carthage teljes irányítást hagy az Xcode konfigurációja felett a fejlesztőnek. Ez azt jelenti, hogy a függőségek telepítése után kézzel kell hozzáadni a keretrendszereket az Xcode-hoz (lásd a «Carthage-keretrendszerek integrálása az Xcode-ba» szakaszt). A Carthage emellett megköveteli, hogy minden függőség tartalmazzon egy Xcode-projektet vagy workspace-t keretrendszer-céllal — ellenkező esetben az építés hibával végződik.

Keretrendszerek építése: bootstrap és update

Carthage három fő parancsot kínál a függőségekkel való munkához: bootstrap, update és build. A carthage bootstrap a meglévő Cartfile.resolved-ból építi a függőségeket — ajánlott CI-környezetekhez és a projekthez csatlakozó fejlesztőknek. A carthage update frissíti a Cartfile.resolved-ot a legújabb verziókra (figyelembe véve a Cartfile korlátait) és elvégzi az építést. A carthage build az összes megadott függőséget felépíti a verziók rögzítése nélkül.

# Első telepítés (frissíti a verziókat)
carthage update --use-xcframeworks --platform iOS

# Újraépítés rögzített verziók alapján
carthage bootstrap --use-xcframeworks --platform iOS

# Csak egy függőség építése
carthage build Alamofire --platform iOS

A --use-xcframeworks jelző arra utasítja a Carthage-t, hogy univerzális .xcframework-eket építsen az elavult .framework-ek helyett. Ez biztosítja a szimulátor és a valódi eszköz, valamint az Apple Silicon Mac támogatását további szkriptek nélkül. A --platform iOS jelző egyetlen iOS platformra korlátozza az építést — ez jelentősen felgyorsítja a folyamatot, különösen ha a projekt többplatformos könyvtárakat tartalmaz.

Carthage támogatja a párhuzamos építést a --cache-builds jelzőn keresztül, amely gyorsítótárazza a már felépített keretrendszereket. Újraépítéskor a Carthage ellenőrzi a Git commit hash-t, és ha a kód nem változott, kihagyja a fordítást. CI-szerverekhez ajánlott a Carthage/Build/ és ~/Library/Caches/carthage/ könyvtárak gyorsítótárazása. A Carthage támogatja továbbá a --verbose-ot részletes naplózáshoz és a --no-use-binaries-t a kényszerített forráskódból építéshez (ha a fejlesztő nem bízik az előre összeállított binárisokban).

Carthage-keretrendszerek integrálása az Xcode-ba

Integráció a Carthage-keretrendszerek Xcode-ba történő kézi integrációja négy lépésben történik. A carthage update vagy bootstrap végrehajtása után az összes épített keretrendszer a Carthage/Build/iOS/-ben (vagy a megfelelő platformon) található. A fejlesztő megnyitja az Xcode-projektet, kiválasztja az alkalmazás célját és hozzáadja a keretrendszereket a General → Frameworks, Libraries, and Embedded Content menüpontban. A futásidejű keretrendszerekhez (dinamikus könyvtárak) ki kell választani az «Embed & Sign»-ot — különben az alkalmazás összeomlik indításkor a «dyld: Library not loaded» hibával.

Carthage a statikus könyvtárak esetén egyszerűbben működik — ezek nem igényelnek beágyazási fázist, mivel közvetlenül az alkalmazás végrehajtható fájljához kapcsolódnak. A Carthage azonban alapértelmezés szerint dinamikus keretrendszereket épít (kivéve az explicit módon konfigurált statikus könyvtárakat). Azoknál a projekteknél, ahol fontos az alkalmazásméret minimalizálása, ajánlott a statikus linkelés használata az Xcode beállításain keresztül.

Kiegészítő lépés — Input Files hozzáadása a Build Phase → Run Script-ben. A Carthage szkriptet igényel a szimulátor-összetevők eltávolításához az épített keretrendszerből (strip simulator architectures). Ez a szkript szükséges az App Store-építésekhez:

# Run Script a(z) 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 nem igényli a .xcworkspace használatát — az összes függőség már bináris keretrendszerekké van építve. A Carthage közvetlenül a .xcodeproj-val dolgozik, ellentétben a CocoaPods-szal, amely workspace-t hoz létre. Ez leegyszerűsíti a verziókezelést és a CI konfigurációját, mivel a Carthage-függőségek nem változtatják meg az Xcode-projekt konfigurációját. Az egyetlen változás — a keretrendszerek hozzáadása a célhoz, ami a .pbxproj-ban rögzül.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods és Swift Package Manager (SPM) — a három fő függőségkezelő az iOS-fejlesztésben. A Carthage decentralizált megközelítésével tűnik ki, a CocoaPods központosított nyilvántartást kínál, az SPM — egy beépített megoldást az Apple-től. A köztük lévő választás a projekt követelményeitől, a csapat méretétől és a szükséges automatizálási szinttől függ.

Carthage olyan projektekhez választják, ahol minimális beavatkozás szükséges az Xcode konfigurációjába és teljes irányítás az integrációs folyamat felett. A Carthage ideális nyílt könyvtárakhoz és keretrendszerekhez, ahol a szerző lehetőséget akar adni a felhasználóknak a függőségek önálló építésére. A Carthage népszerű a UNIX filozófiát értékelő fejlesztők körében is: minden eszköz egy dolgot csinál jól. A CocoaPods továbbra is szabvány marad a több tucat függőséggel rendelkező vállalati projekteknél, ahol fontos az automatizálás. Az SPM — választás új projektekhez, mivel be van építve az Xcode-ba és aktívan fejleszti az Apple.

Migráció a kezelők között eltérő megközelítést igényel. Carthage → SPM: távolítsa el a keretrendszereket az Xcode-ból, törölje a Cartfile-t és adja hozzá a Package Dependencies-t a File → Add Package Dependencies-en keresztül. Carthage → CocoaPods: távolítsa el a Carthage-keretrendszereket, hozzon létre Podfile-t, adja hozzá a függőségeket és futtassa a pod init && pod install-t. A Carthage-ről CocoaPods-ra vagy SPM-re való migráció során megszűnik a keretrendszerek kézi frissítésének szükségessége — az összes függőség egy paranccsal frissíthető. A Carthage továbbra is releváns olyan projekteknél, ahol fontos elkerülni a vendor lock-in-t és megőrizni a függőségépítés átláthatóságát.

Gyakori problémák és megoldásuk

Carthage — egy stabil eszköz, de a fejlesztők időnként tipikus problémákba ütköznek, különösen CI-szervereken történő építéskor, Xcode frissítésekor vagy Swift-verziók váltásakor. A legtöbb probléma megoldható a gyorsítótár törlésével, a --use-xcframeworks helyes konfigurálásával és a minimális iOS-verzió összeférhetőségének ellenőrzésével.

«The file manager returned an error» hiba — a Carthage gyorsítótár sérülésekor vagy fájlhozzáférési jogosultsági konfliktus esetén jelentkezik. Megoldás: törölje a gyorsítótárat a rm -rf ~/Library/Caches/carthage paranccsal és indítsa újra a carthage bootstrap-et. Segít a Carthage/ könyvtár eltávolítása a projektből és az újraépítés is. CI-szervereken a Carthage gyorsítótárat csak a Cartfile.resolved változásakor szabad frissíteni.

«No such module» hiba — a keretrendszer nem található az Xcode-ban, bár a Carthage-építés sikeresen befejeződött. Megoldás: ellenőrizze a keretrendszer elérési útját a General → Frameworks, Libraries, and Embedded Content-ben. A keretrendszernek a Carthage/Build/iOS/-ben kell lennie. Győződjön meg arról, hogy a .xcframework helyesen lett hozzáadva (húzza újra). Dinamikus keretrendszereknél ellenőrizze az Embed & Sign-ot. Ha a hiba továbbra is fennáll — adja hozzá a FRAMEWORK_SEARCH_PATHS-t a Build Settings-ben.

Építési hiba Swift-inkompatibilitás miatt — a könyvtár más Swift-verzióhoz készült, mint a projekt. Megoldás: használja a carthage update --no-use-binaries-t a kényszerített forráskódból építéshez ugyanazzal a Swift-verzióval. Ha a könyvtár nem fordítható le az aktuális verzió alatt — használjon .xcconfig-ot a Swift-verzió megadásához vagy fork-olja a könyvtárat. A Carthage 0.39-től kezdve a --use-xcframeworks automatikusan tartalmazza a megfelelő Swift-verziót a binárisban.

CI-építési problémák — a Carthage CI-n helyes gyorsítótár-konfigurációt igényel. Megoldás: gyorsítótárazza a Carthage/Build/ és ~/Library/Caches/carthage/ könyvtárakat. CI-n a carthage bootstrap --use-xcframeworks --platform iOS-t használja az update helyett, hogy ne változzanak a verziók. GitHub Actions-hoz elérhető a hivatalos Carthage action. Jenkins-hez — a CarthageBuild bővítmény. A Carthage összeomolhat GUI nélküli macOS-en — megoldás: telepítse a brew install xcode-build-server-t vagy adja hozzá a -UseModernBuildSystem=NO kapcsolót.