Carthage: nedir, merkezi olmayan bağımlılık yöneticisi

Carthage nedir?

Carthage, 2014 yılında Swift topluluğundan geliştiriciler tarafından oluşturulan merkezi olmayan mimariye sahip bir bağımlılık yöneticisidir. Carthage merkezi bir spesifikasyon kaydı kullanmaz — her kütüphane URL veya GitHub adı aracılığıyla doğrudan bir Git deposundan bağlanır. Carthage kaynak kodunu indirir, onu ikili bir framework'e (.xcframework veya .framework) dönüştürür ve geliştiriciye bir Xcode projesine manuel entegrasyon için hazır bir yapıt sağlar.

Carthage'ın mimarisi üç bileşen içerir: CLI aracı carthage, yapılandırma dosyası Cartfile ve oluşturulan framework'lerin bulunduğu Carthage/Build/ dizini. Carthage ve CocoaPods arasındaki temel fark, .xcodeproj'nin otomatik olarak değiştirilmemesidir. Carthage .xcworkspace oluşturmaz, derleyici flag'lerini yapılandırmaz ve Pods.xcconfig oluşturmaz. Geliştirici, Xcode aracılığıyla projeye manuel olarak framework'leri ekler ve entegrasyon süreci üzerinde tam kontrol sağlar.

Carthage, çok çekirdekli işlemcilerde süreci önemli ölçüde hızlandıran paralel bağımlılık derlemesi kullanır. Her bağımlılık ayrı bir hedef olarak oluşturulur ve Carthage geçişli bağımlılıkların grafiğini otomatik olarak çözerek bunları doğru sırayla oluşturur. Topluluk kıyaslamalarına göre Carthage, modern Mac'lerde ortalama 30–60 saniyede 15–20 bağımlılık oluşturur ve bu, çok sayıda kütüphane içeren projeler için CocoaPods'tan daha hızlıdır. Carthage tüm Apple platformlarını destekler: iOS, macOS, watchOS ve tvOS ve sürüm 0.38+'dan itibaren — simülatör ve Apple Silicon cihaz desteği için evrensel .xcframework oluşturur.

Carthage nasıl çalışır

Carthage her bağımlılığın Git deposunu klonlar, belirtilen sürüme (etiket, commit veya dal) geçer ve framework'ü oluşturmak için xcodebuild'i çalıştırır. Carthage, derleme şemasına göre Xcode proje türünü (framework, dynamic framework, statik kütüphane) otomatik olarak belirler. Bir projenin birden fazla şeması varsa, Carthage varsayılan şemayı (alfabetik sırada ilk) kullanır. Derlemeden sonra Carthage, bitmiş framework'ü Carthage/Build/ dizinine kopyalar ve tam sürüm sabitlemesiyle Cartfile.resolved dosyası oluşturur. Carthage, oluşturulan framework'lerin önbelleğe alınmasını destekler — bağımlılıklarda değişiklik olmadan yeniden derleme atlanır.

Carthage'da geçişli bağımlılıklar Cartfile.resolved aracılığıyla yönetilir: Carthage gerekli tüm bağımlılıkların bir grafiğini oluşturur ve bunları doğru sırayla oluşturur. İki kütüphane aynı üçüncü taraf kütüphanesine bağımlıysa, Carthage onu bir kez oluşturur ve her ikisi için de kullanır. Carthage, belirli hedefi ve nedeni belirten derleme hatalarını raporlar — bu, sorun teşhisini basitleştirir.

Cartfile: yapı, sözdizimi ve örnekler

Cartfile, bir Carthage projesinin bağımlılıklarını tanımlayan Ruby benzeri sözdizimine (Cartfile formatı) sahip bir yapılandırma dosyasıdır. Cartfile, proje kökünde .xcodeproj'nin yanında bulunur. Cartfile'ın her satırı bir bağımlılığı tanımlar: kaynak (Git URL'si, GitHub deposu) ve sürüm. Sözdizimi, etiketler, commit'ler ve dallar aracılığıyla sürüm sabitlemeyi destekler.

# Temel bağımlılıklar Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

github "Owner/Repo" yönergesi, GitHub depoları için bir kısaltmadır. Carthage otomatik olarak https://github.com/Owner/Repo.git URL'sini oluşturur. GitLab, Bitbucket ve diğer Git sunucuları için tam URL kullanılır: git "https://gitlab.com/owner/repo.git". Sürüm operatörleri: ~> 5.9 (5.9'dan 6.0'a kadar herhangi bir sürüm, 6.0 hariç), == 8.0.0 (tam sürüm), >= 1.0 (minimum sürüm). Belirli bir commit, github "owner/repo" "abc1234" ile sabitlenebilir.

Tam Cartfile örneği

Carthage farklı yapılandırmalar için birden çok dizini destekler: Cartfile (ana), Cartfile.private (yayınlanmayan dahili bağımlılıklar için) ve Cartfile.resolved (otomatik oluşturulur). Özel bağımlılıklar, test framework'leri gibi yalnızca geliştirme derlemelerinde kullanılan kütüphaneler için kullanışlıdır.

# Cartfile — ana bağımlılıklar
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

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

# Geliştirme dalı
github "marmelroy/PhoneNumberKit" "development"

github ve git, Cartfile'daki iki kaynak türüdür. İlki yalnızca GitHub içindir ve otomatik olarak URL oluşturur. İkincisi, tam URL'ye sahip herhangi bir genel veya özel Git deposu içindir. Bir sürüm, etiket (== 2.1.1), anlamsal aralık (~> 5.9), dal adı ("development") veya commit hash'i ("a1b2c3d") olarak belirtilebilir. SemVer'i takip eden bağımlılıklar için anlamsal aralıklar (~>) önerilir — bu, güncellemeler sırasında yıkıcı değişikliklere karşı korur.

Cartfile.resolved, carthage update'den sonra otomatik olarak oluşturulur. Geçişli olanlar dahil tüm yüklü bağımlılıkların tam sürümlerini sabitler. Bu dosya Git'te saklanmalıdır — onsuz, başka bir makinede carthage bootstrap komutu aynı kurallarla kütüphaneleri oluşturacaktır, ancak sürümler farklılık gösterebilir. carthage outdated, yeni sürümleri mevcut olan güncel olmayan bağımlılıkların bir listesini gösterir.

Carthage kurulumu ve yapılandırması

Carthage, Homebrew (macOS için standart paket yöneticisi) aracılığıyla kurulur. Alternatif yöntemler: GitHub'dan oluşturulmuş bir .pkg yükleyiciden kurulum veya kaynaktan derleme. Carthage, Xcode with Command Line Tools (xcodebuild dahil) gerektirir ve Apple Silicon Mac'te bazı eski bağımlılıklar için Rosetta 2 gerekir.

# Kurulum Carthage aracılığıyla Homebrew
brew install carthage

# Sürüm kontrolü
carthage version

# .pkg üzerinden kurulum (eğer Homebrew mevcut değilse)
# İndir Carthage.pkg'yi GitHub Releases adresinden indirip manuel kurun

Carthage'ı kurduktan sonra, proje başlatma işlemi proje kökünde bir Cartfile oluşturarak başlar. Carthage'ın init komutu yoktur — dosya bir metin düzenleyicide manuel olarak oluşturulur. Cartfile'ı bağımlılıklarla doldurduktan sonra, geliştirici carthage bootstrap (zaten Cartfile.resolved varsa) veya carthage update (ilk kurulum veya güncelleme) komutunu çalıştırır. Carthage depoları klonlar, framework'leri oluşturur ve bunları Carthage/Build/ dizinine yerleştirir.

Carthage'ı güncelleme brew upgrade carthage ile yapılır. Sürüm carthage version ile kontrol edilir. 2025 ortası itibarıyla en son kararlı sürüm, varsayılan .xcframework desteği, geliştirilmiş paralel derleme ve tam Swift 6 desteği ile 0.40'tır. Sürüm 0.39'dan itibaren Carthage, uyumluluk shim'i olmadan eski .framework oluşturmayı durdurmuştur — açıkça --use-xcframeworks belirtilmesi önerilir.

# Güncelleme Carthage aracılığıyla Homebrew
brew upgrade carthage

# Belirli bir sürümü yükleme
brew install carthage@0.39

# Tamamen yeniden kurulum
brew uninstall carthage && brew install carthage

Not: Carthage .xcworkspace oluşturmaz ve .xcodeproj'yi değiştirmez. CocoaPods'un aksine, Carthage Xcode yapılandırmasının tam kontrolünü geliştiriciye bırakır. Bu, bağımlılıkları kurduktan sonra framework'leri manuel olarak Xcode'a eklemeniz gerektiği anlamına gelir (bkz. «Carthage framework'lerini Xcode'a entegre etme» bölümü). Carthage ayrıca her bağımlılığın bir framework hedefi içeren bir Xcode projesi veya çalışma alanı içermesini gerektirir — aksi takdirde derleme başarısız olur.

Framework oluşturma: bootstrap ve update

Carthage, bağımlılıklarla çalışmak için üç ana komut sunar: bootstrap, update ve build. carthage bootstrap, mevcut bir Cartfile.resolved dosyasından bağımlılıkları oluşturur — CI ortamları ve projeye katılan geliştiriciler için önerilir. carthage update, Cartfile.resolved dosyasını en son sürümlere (Cartfile kısıtlamalarına saygı göstererek) günceller ve derlemeyi gerçekleştirir. carthage build, sürümleri kaydetmeden belirtilen tüm bağımlılıkları oluşturur.

# İlk kurulum (sürümleri günceller)
carthage update --use-xcframeworks --platform iOS

# Sabitlenmiş sürümlerle yeniden derleme
carthage bootstrap --use-xcframeworks --platform iOS

# Yalnızca bir bağımlılık oluştur
carthage build Alamofire --platform iOS

--use-xcframeworks flag'i, Carthage'a eski .framework yerine evrensel .xcframework oluşturmasını söyler. Bu, hem simülatör hem de gerçek bir cihaz için ve ayrıca ek komut dosyası olmadan Apple Silicon Mac'ler için destek sağlar. --platform iOS flag'i, derlemeyi tek bir iOS platformuyla sınırlar — bu, özellikle proje platformlar arası kütüphaneler içeriyorsa süreci önemli ölçüde hızlandırır.

Carthage, zaten oluşturulmuş framework'leri önbelleğe alan --cache-builds flag'i aracılığıyla paralel derlemeyi destekler. Yeniden derleme sırasında Carthage, Git commit hash'ini kontrol eder ve kod değişmemişse derlemeyi atlar. CI sunucuları için Carthage/Build/ dizini ve ~/Library/Caches/carthage/ önbelleğe alınması önerilir. Carthage ayrıca ayrıntılı günlük kaydı için --verbose ve kaynaktan zorunlu derleme için --no-use-binaries (geliştirici önceden oluşturulmuş ikili dosyalara güvenmiyorsa) destekler.

Carthage framework'lerini Xcode'a entegre etme

Entegrasyon Carthage framework'lerinin Xcode'a entegrasyonu dört adımda manuel olarak yapılır. carthage update veya bootstrap çalıştırıldıktan sonra, oluşturulan tüm framework'ler Carthage/Build/iOS/ (veya ilgili platform) içinde bulunur. Geliştirici Xcode projesini açar, uygulama hedefini seçer ve framework'leri General → Frameworks, Libraries, and Embedded Content'e ekler. Çalışma zamanı framework'leri (dinamik kütüphaneler) için «Embed & Sign» seçilmelidir — aksi takdirde uygulama başlatılırken «dyld: Library not loaded» hatasıyla çöker.

Carthage statik kütüphaneler için daha basittir — doğrudan uygulamanın yürütülebilir dosyasına bağlandıkları için gömme aşaması gerektirmezler. Ancak Carthage, varsayılan olarak dinamik framework'ler oluşturur (açıkça yapılandırılmış statik kütüphaneler hariç). Uygulama boyutunu en aza indirmenin önemli olduğu projeler için Xcode ayarları aracılığıyla statik bağlama önerilir.

Ek bir adım, Build Phase → Run Script'e Input Files eklemektir. Carthage, oluşturulan framework'ten simülatör yapıtlarını kaldırmak için bir komut dosyası gerektirir (strip simulator architectures). Bu komut dosyası App Store derlemeleri için gereklidir:

# Run Script için 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 kullanımını gerektirmez — tüm bağımlılıklar zaten ikili framework'lere dönüştürülmüştür. Carthage, bir çalışma alanı oluşturan CocoaPods'un aksine doğrudan .xcodeproj ile çalışır. Bu, Carthage bağımlılıkları Xcode proje yapılandırmasını değiştirmediği için sürüm kontrolünü ve CI kurulumunu basitleştirir. Tek değişiklik, hedefe framework eklemektir ve bu .pbxproj dosyasına kaydedilir.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods ve Swift Package Manager (SPM), iOS geliştirmedeki üç ana bağımlılık yöneticisidir. Carthage merkezi olmayan yaklaşımıyla öne çıkar, CocoaPods merkezi bir kayıt sunar ve SPM, Apple'ın entegre çözümüdür. Bunlar arasındaki seçim, proje gereksinimlerine, ekip büyüklüğüne ve istenen otomasyon düzeyine bağlıdır.

Carthage, Xcode yapılandırmasına minimum müdahale ve entegrasyon süreci üzerinde tam kontrol gerektiren projeler için seçilir. Carthage, yazarın kullanıcıların bağımlılıkları bağımsız olarak oluşturmasına izin vermek istediği açık kaynak kütüphaneler ve framework'ler için idealdir. Carthage ayrıca UNIX felsefesine değer veren geliştiriciler arasında da popülerdir: her araç bir işi iyi yapar. CocoaPods, otomasyonun önemli olduğu düzinelerce bağımlılığa sahip kurumsal projeler için standart olmaya devam etmektedir. SPM, Xcode'a entegre olduğu ve Apple tarafından aktif olarak geliştirildiği için yeni projeler için tercih edilir.

Geçiş yöneticiler arasında farklı yaklaşımlar gerektirir. Carthage → SPM: framework'leri Xcode'dan kaldırın, Cartfile'ı silin ve File → Add Package Dependencies aracılığıyla Package Dependencies ekleyin. Carthage → CocoaPods: Carthage framework'lerini kaldırın, bir Podfile oluşturun, bağımlılıkları ekleyin ve pod init && pod install komutunu çalıştırın. Carthage'dan CocoaPods veya SPM'ye geçiş yaparken, framework'leri manuel olarak güncelleme ihtiyacı ortadan kalkar — tüm bağımlılıklar tek bir komutla güncellenir. Carthage, satıcı kilitlemesinden kaçınmanın ve bağımlılık derlemesinin şeffaflığını korumanın önemli olduğu projeler için geçerliliğini korur.

Yaygın sorunlar ve çözümleri

Carthage istikrarlı bir araçtır, ancak geliştiriciler özellikle CI sunucularında derleme yaparken, Xcode'u güncellerken veya Swift sürümlerini değiştirirken periyodik olarak tipik sorunlarla karşılaşır. Çoğu sorun, önbelleği temizleyerek, --use-xcframeworks doğru yapılandırarak ve minimum iOS sürümünü kontrol ederek çözülür.

«The file manager returned an error» hatası — Carthage önbelleği bozulduğunda veya dosya izin çakışması olduğunda oluşur. Çözüm: rm -rf ~/Library/Caches/carthage ile önbelleği silin ve carthage bootstrap komutunu yeniden başlatın. Projedeki Carthage/ dizinini silmek ve yeniden derlemek de yardımcı olur. CI sunucularında, Carthage önbelleği yalnızca Cartfile.resolved değiştiğinde güncellenmelidir.

«No such module» hatası — Carthage derlemesi başarılı olmasına rağmen framework Xcode'da bulunamaz. Çözüm: General → Frameworks, Libraries, and Embedded Content içinde framework yolunu kontrol edin. Framework Carthage/Build/iOS/ içinde olmalıdır. .xcframework'ün doğru eklendiğinden emin olun (yeniden sürükleyin). Dinamik framework'ler için Embed & Sign'ı kontrol edin. Hata devam ederse, Build Settings'e FRAMEWORK_SEARCH_PATHS ekleyin.

Swift uyumsuzluğu nedeniyle derleme hatası — kütüphane, projeden farklı bir Swift sürümü için derlenmiştir. Çözüm: aynı Swift sürümüyle kaynaktan derlemeye zorlamak için carthage update --no-use-binaries kullanın. Kütüphane mevcut sürüm altında derlenmezse, Swift sürümünü belirtmek için .xcconfig kullanın veya kütüphaneyi fork edin. Carthage 0.39'dan itibaren, --use-xcframeworks otomatik olarak ikili dosyaya doğru Swift sürümünü ekler.

CI derleme sorunları — CI'da Carthage, uygun önbellek yapılandırması gerektirir. Çözüm: Carthage/Build/ ve ~/Library/Caches/carthage/ önbelleğe alın. Sürümleri değiştirmemek için CI'da güncelleme yerine carthage bootstrap --use-xcframeworks --platform iOS kullanın. GitHub Actions için resmi bir Carthage eylemi mevcuttur. Jenkins için — CarthageBuild eklentisi. Carthage, GUI olmayan macOS'ta çökebilir — çözüm: brew install xcode-build-server kurun veya -UseModernBuildSystem=NO flag'ini ekleyin.