Carthage: ce este, manager de dependențe descentralizat

Ce este Carthage?

Carthage — un manager de dependențe cu arhitectură descentralizată, creat în 2014 de dezvoltatorii din comunitatea Swift. Carthage nu folosește un registru central de specificații — fiecare bibliotecă se conectează direct din repositoriul Git prin URL sau nume pe GitHub. Carthage descarcă codul sursă, îl construiește într-un framework binar (.xcframework sau .framework) și oferă dezvoltatorului un artefact gata pentru integrare manuală în proiectul Xcode.

Arhitectura Carthage include trei componente: instrumentul CLI carthage, fișierul de configurare Cartfile și directorul Carthage/Build/ cu framework-urile construite. Diferența principală dintre Carthage și CocoaPods — absența modificării automate a .xcodeproj. Carthage nu creează .xcworkspace, nu configurează flag-uri de compilator și nu generează Pods.xcconfig. Dezvoltatorul adaugă manual framework-urile în proiect prin Xcode, ceea ce oferă un control complet asupra procesului de integrare.

Carthage folosește construirea paralelă a dependențelor, ceea ce accelerează semnificativ procesul pe procesoare multi-core. Fiecare dependență este construită ca un target separat, iar Carthage rezolvă automat graful dependențelor tranzitive, construindu-le în ordinea corectă. Conform benchmark-urilor comunității, Carthage construiește 15–20 de dependențe în medie în 30–60 de secunde pe Mac-uri moderne, ceea ce este mai rapid decât CocoaPods pentru proiecte cu multe biblioteci. Carthage suportă toate platformele Apple: iOS, macOS, watchOS și tvOS, iar de la versiunea 0.38+ — construirea .xcframework universale pentru suportul simulatorelor și dispozitivelor Apple Silicon.

Cum funcționează Carthage

Carthage clonează repositoriul Git al fiecărei dependențe, comută pe versiunea specificată (tag, commit sau branch) și lansează xcodebuild pentru construirea framework-ului. Carthage determină tipul proiectului Xcode (framework, dynamic framework, bibliotecă statică) automat după schema de construire. Dacă proiectul conține mai multe scheme, Carthage folosește schema implicită (prima în ordine alfabetică). După construire, Carthage copiază framework-ul finit în Carthage/Build/ și creează fișierul Cartfile.resolved cu fixarea versiunilor exacte. Carthage suportă cache-ul framework-urilor construite — reconstruirea fără modificări ale dependențelor nu se execută.

Dependențele tranzitive în Carthage sunt gestionate prin Cartfile.resolved: Carthage construiește graful tuturor dependențelor necesare și le construiește în ordinea corectă. Dacă două biblioteci depind de aceeași bibliotecă terță, Carthage o construiește o singură dată și o folosește pentru ambele. Carthage notifică erorile de construire cu indicarea target-ului specific și a cauzei — aceasta simplifică diagnosticarea problemelor.

Cartfile: structură, sintaxă și exemple

Cartfile — fișier de configurare în limbajul Ruby (format Cartfile) care definește dependențele proiectului Carthage. Cartfile se află în rădăcina proiectului lângă .xcodeproj. Fiecare linie din Cartfile descrie o dependență: sursa (URL Git, repositoriu GitHub) și versiunea. Sintaxa suportă fixarea versiunilor prin tag-uri, commit-uri și branch-uri.

# Dependențe de bază Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Directiva github "Owner/Repo" — formă scurtă pentru repositoriile GitHub. Carthage construiește automat URL-ul sub forma https://github.com/Owner/Repo.git. Pentru GitLab, Bitbucket și alte host-uri Git se folosește URL-ul complet: git "https://gitlab.com/owner/repo.git". Operatori de versiune: ~> 5.9 (orice versiune de la 5.9 la 6.0 excluzând 6.0), == 8.0.0 (versiune exactă), >= 1.0 (versiune minimă). Conectarea unui commit specific se poate face prin github "owner/repo" "abc1234".

Exemplu complet de Cartfile

Carthage suportă mai multe directoare pentru configurații diferite: Cartfile(principal), Cartfile.private (pentru dependențe interne care nu se publică) și Cartfile.resolved (generat automat). Dependențele private sunt utile pentru bibliotecile folosite doar în construirea Development, de exemplu framework-uri de testare.

# Cartfile — dependențe principale
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# Complet URL pentru GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Branch de dezvoltare
github "marmelroy/PhoneNumberKit" "development"

github și git — două tipuri de surse în Cartfile. Primul este destinat exclusiv GitHub și formează automat URL-ul. Al doilea — pentru orice repositoriu Git public sau privat cu URL complet. Versiunea poate fi specificată prin tag (== 2.1.1), interval semantic (~> 5.9), nume de branch ("development") sau hash de commit ("a1b2c3d"). Utilizarea intervalelor semantice (~>) este recomandată pentru dependențele care respectă SemVer — aceasta protejează de modificări destructurante la actualizare.

Cartfile.resolved este generat automat după carthage update. Acesta fixează versiunile exacte ale tuturor dependențelor instalate, inclusiv cele tranzitive. Fișierul trebuie păstrat în Git — fără el comanda carthage bootstrap pe altă mașină va construi bibliotecile după aceleași reguli, dar versiunile pot diferi. carthage outdated arată lista dependențelor învechite pentru care sunt disponibile versiuni noi.

Instalarea și configurarea Carthage

Carthage se instalează prin Homebrew — managerul standard de pachete pentru macOS. Metode alternative: instalarea din instalatorul .pkg gata făcut de pe GitHub sau construirea din cod sursă. Carthage necesită Xcode cu Command Line Tools (inclusiv xcodebuild), iar pe Apple Silicon Mac — Rosetta 2 pentru unele dependențe mai vechi.

# Instalare Carthage prin Homebrew
brew install carthage

# Verificarea versiunii
carthage version

# Instalare din .pkg (dacă Homebrew este indisponibil)
# Descărcați Carthage.pkg de pe GitHub Releases și instalați manual

După instalare, inițializarea proiectului Carthage începe cu crearea Cartfile în rădăcina proiectului. Carthage nu are comanda init — fișierul se creează manual într-un editor de text. După completarea Cartfile-ului cu dependențe, dezvoltatorul lansează carthage bootstrap (dacă Cartfile.resolved există deja) sau carthage update (instalare inițială sau actualizare). Carthage clonează repositoriile, construiește framework-urile și le plasează în Carthage/Build/.

Actualizarea Carthage se face prin brew upgrade carthage. Versiunea se verifică cu comanda carthage version. Ultima versiune stabilă la mid-2025 — 0.40 cu suport implicit pentru .xcframework, construire paralelă îmbunătățită și suport complet pentru Swift 6. Începând cu versiunea 0.39, Carthage a încetat să construiască .framework învechite fără punte de compatibilitate — se recomandă specificarea explicită a --use-xcframeworks.

# Actualizare Carthage prin Homebrew
brew upgrade carthage

# Instalarea unei versiuni specifice
brew install carthage@0.39

# Reinstalare completă
brew uninstall carthage && brew install carthage

Notă: Carthage nu creează .xcworkspace și nu modifică .xcodeproj. Spre deosebire de CocoaPods, Carthage lasă controlul complet al configurației Xcode dezvoltatorului. Aceasta înseamnă că după instalarea dependențelor trebuie să adăugați manual framework-urile în Xcode (a se vedea secțiunea «Integrarea framework-urilor Carthage în Xcode»). Carthage necesită, de asemenea, ca fiecare dependență să conțină un proiect Xcode sau workspace cu un target de framework — altfel construirea se va încheia cu eroare.

Construirea framework-urilor: bootstrap și update

Carthage oferă trei comenzi principale pentru lucrul cu dependențele: bootstrap, update și build. carthage bootstrap construiește dependențele din Cartfile.resolved existent — recomandat pentru medii CI și dezvoltatori care se alătură proiectului. carthage update actualizează Cartfile.resolved la cele mai noi versiuni (ținând cont de restricțiile Cartfile) și execută construirea. carthage build construiește toate dependențele specificate fără fixarea versiunilor.

# Instalare inițială (actualizează versiunile)
carthage update --use-xcframeworks --platform iOS

# Reconstruire după versiuni fixate
carthage bootstrap --use-xcframeworks --platform iOS

# Construirea unei singure dependențe
carthage build Alamofire --platform iOS

Flag-ul --use-xcframeworks indică Carthage să construiască .xcframework universale în locul .framework învechite. Aceasta asigură suportul atât pentru simulator, cât și pentru dispozitivul real, precum și pentru Apple Silicon Mac fără scripturi suplimentare. Flag-ul --platform iOS limitează construirea la o singură platformă iOS — aceasta accelerează semnificativ procesul, mai ales dacă în proiect sunt specificate biblioteci cross-platform.

Carthage suportă construirea paralelă prin flag-ul --cache-builds, care pune în cache framework-urile deja construite. La reconstruire, Carthage verifică hash-ul commit-ului Git și, dacă codul nu s-a modificat, omite compilarea. Pentru serverele CI se recomandă cache-ul directorului Carthage/Build/ și ~/Library/Caches/carthage/. Carthage suportă, de asemenea, --verbose pentru logare detaliată și --no-use-binaries pentru construirea forțată din cod sursă (dacă dezvoltatorul nu are încredere în binarele pre-construite).

Integrarea framework-urilor Carthage în Xcode

Integrarea framework-urilor Carthage în Xcode se face manual în patru pași. După executarea carthage update sau bootstrap toate framework-urile construite se află în Carthage/Build/iOS/ (sau platforma corespunzătoare). Dezvoltatorul deschide proiectul Xcode, selectează target-ul aplicației și adaugă framework-urile în General → Frameworks, Libraries, and Embedded Content. Pentru framework-urile de runtime (biblioteci dinamice) trebuie selectat «Embed & Sign» — altfel aplicația va crash-ui la pornire cu eroarea «dyld: Library not loaded».

Carthage pentru bibliotecile statice funcționează mai simplu — ele nu necesită faza de embed, deoarece se link-uiesc direct în fișierul executabil al aplicației. Cu toate acestea, Carthage construiește în mod implicit framework-uri dinamice (cu excepția bibliotecilor statice configurate explicit). Pentru proiecte unde este importantă minimizarea dimensiunii aplicației, se recomandă utilizarea link-uirii statice prin setările Xcode.

Pas suplimentar — adăugarea Input Files în Build Phase → Run Script. Carthage necesită un script pentru eliminarea artefactelor simulatorului din framework-ul construit (strip simulator architectures). Acest script este necesar pentru construirea pentru App Store:

# Run Script pentru 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 nu necesită utilizarea .xcworkspace — toate dependențele sunt deja construite în framework-uri binare. Carthage lucrează direct cu .xcodeproj, spre deosebire de CocoaPods care creează workspace. Aceasta simplifică controlul versiunilor și configurarea CI, deoarece dependențele Carthage nu modifică configurația proiectului Xcode. Singura modificare — adăugarea framework-urilor în target, care se fixează în .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods și Swift Package Manager (SPM) — cei trei principali manageri de dependențe în dezvoltarea iOS. Carthage se diferențiază prin abordarea descentralizată, CocoaPods oferă un registru centralizat, SPM — soluția încorporată de la Apple. Alegerea între ei depinde de cerințele proiectului, dimensiunea echipei și nivelul necesar de automatizare.

Carthage este ales pentru proiecte care necesită intervenție minimă în configurația Xcode și control complet asupra procesului de integrare. Carthage este ideal pentru biblioteci deschise și framework-uri, unde autorul dorește să ofere utilizatorilor posibilitatea de a construi dependențele independent. Carthage este popular și în comunitatea dezvoltatorilor care apreciază filozofia UNIX: fiecare instrument face un lucru bine. CocoaPods rămâne standardul pentru proiecte corporative cu zeci de dependențe, unde automatizarea este importantă. SPM — alegerea pentru proiecte noi, deoarece este încorporat în Xcode și este dezvoltat activ de Apple.

Migrarea între manageri necesită abordări diferite. Carthage → SPM: eliminați framework-urile din Xcode, ștergeți Cartfile și adăugați Package Dependencies prin File → Add Package Dependencies. Carthage → CocoaPods: eliminați framework-urile Carthage, creați Podfile, adăugați dependențe și executați pod init && pod install. La migrarea de la Carthage la CocoaPods sau SPM dispare necesitatea actualizării manuale a framework-urilor — toate dependențele se actualizează cu o singură comandă. Carthage rămâne relevant pentru proiecte unde este important să se evite vendor lock-in și să se păstreze transparența construirii dependențelor.

Probleme comune și soluționarea lor

Carthage — un instrument stabil, dar dezvoltatorii întâmpină ocazional probleme tipice, în special la construirea pe servere CI, actualizarea Xcode sau schimbarea versiunilor Swift. Majoritatea problemelor se rezolvă prin curățarea cache-ului, configurarea corectă a --use-xcframeworks și verificarea conformității versiunii minime iOS.

Eroarea «The file manager returned an error» — apare la deteriorarea cache-ului Carthage sau conflict de drepturi de fișier. Soluție: ștergeți cache-ul cu comanda rm -rf ~/Library/Caches/carthage și reporniți carthage bootstrap. De asemenea, ajută ștergerea directorului Carthage/ din proiect și reconstruirea. Pe serverele CI, cache-ul Carthage trebuie actualizat doar la modificarea Cartfile.resolved.

Eroarea «No such module» — framework-ul nu a fost găsit în Xcode, deși construirea Carthage s-a încheiat cu succes. Soluție: verificați calea framework-ului în General → Frameworks, Libraries, and Embedded Content. Framework-ul trebuie să fie în Carthage/Build/iOS/. Asigurați-vă că .xcframework a fost adăugat corect (trageți din nou). Pentru framework-urile dinamice verificați Embed & Sign. Dacă eroarea persistă — adăugați FRAMEWORK_SEARCH_PATHS în Build Settings.

Eroare la construire din cauza incompatibilității Swift — biblioteca a fost construită pentru o altă versiune Swift decât proiectul. Soluție: utilizați carthage update --no-use-binaries pentru construirea forțată din cod sursă cu aceeași versiune Swift. Dacă biblioteca nu se compilează sub versiunea curentă — folosiți .xcconfig pentru specificarea versiunii Swift sau fork-uiți biblioteca. Începând cu Carthage 0.39, --use-xcframeworks include automat versiunea corectă Swift în binar.

Probleme cu construirea CI — Carthage pe CI necesită configurarea corectă a cache-ului. Soluție: puneți în cache Carthage/Build/ și ~/Library/Caches/carthage/. Utilizați carthage bootstrap --use-xcframeworks --platform iOS în loc de update pe CI pentru a nu schimba versiunile. Pentru GitHub Actions este disponibilă o acțiune oficială Carthage. Pentru Jenkins — pluginul CarthageBuild. Carthage poate cădea pe macOS fără GUI — soluție: instalați brew install xcode-build-server sau adăugați cheia -UseModernBuildSystem=NO.