Carthage: apa itu, manajer dependensi terdesentralisasi

Apa itu Carthage?

Carthage — manajer dependensi dengan arsitektur terdesentralisasi, dibuat pada tahun 2014 oleh pengembang dari komunitas Swift. Carthage tidak menggunakan register spesifikasi pusat — setiap perpustakaan terhubung langsung dari repositori Git melalui URL atau nama di GitHub. Carthage mengunduh kode sumber, membangunnya menjadi framework biner (.xcframework atau .framework) dan memberikan artefak siap pakai kepada pengembang untuk integrasi manual ke dalam proyek Xcode.

Arsitektur Carthage mencakup tiga komponen: alat CLI carthage, file konfigurasi Cartfile dan direktori Carthage/Build/ dengan framework yang telah dibangun. Perbedaan prinsip Carthage dari CocoaPods — tidak adanya modifikasi otomatis .xcodeproj. Carthage tidak membuat .xcworkspace, tidak mengonfigurasi flag kompiler dan tidak menghasilkan Pods.xcconfig. Pengembang menambahkan framework ke proyek secara manual melalui Xcode, yang memberikan kontrol penuh atas proses integrasi.

Carthage menggunakan pembangunan dependensi paralel, yang secara signifikan mempercepat proses pada prosesor multi-inti. Setiap dependensi dibangun sebagai target terpisah, dan Carthage secara otomatis menyelesaikan graf dependensi transitif, membangunnya dalam urutan yang benar. Menurut benchmark komunitas, Carthage membangun 15-20 dependensi rata-rata dalam 30-60 detik pada Mac modern, yang lebih cepat daripada CocoaPods untuk proyek dengan banyak perpustakaan. Carthage mendukung semua platform Apple: iOS, macOS, watchOS dan tvOS, dan sejak versi 0.38+ — pembangunan .xcframework universal untuk dukungan simulator dan perangkat Apple Silicon.

Bagaimana Carthage bekerja

Carthage mengkloning repositori Git setiap dependensi, beralih ke versi yang ditentukan (tag, commit atau branch) dan menjalankan xcodebuild untuk membangun framework. Carthage menentukan jenis proyek Xcode (framework, dynamic framework, perpustakaan statis) secara otomatis berdasarkan skema pembangunan. Jika proyek berisi beberapa skema, Carthage menggunakan skema default (pertama dalam urutan abjad). Setelah pembangunan, Carthage menyalin framework jadi ke Carthage/Build/ dan membuat file Cartfile.resolved dengan penetapan versi yang tepat. Carthage mendukung caching framework yang telah dibangun — pembangunan ulang tanpa perubahan dependensi tidak dilakukan.

Dependensi transitif di Carthage ditangani melalui Cartfile.resolved: Carthage membangun graf semua dependensi yang diperlukan dan membangunnya dalam urutan yang benar. Jika dua perpustakaan bergantung pada perpustakaan pihak ketiga yang sama, Carthage membangunnya sekali dan menggunakannya untuk keduanya. Carthage memberitahu kesalahan pembangunan dengan menunjukkan target spesifik dan penyebabnya — ini menyederhanakan diagnosis masalah.

Cartfile: struktur, sintaksis dan contoh

Cartfile — file konfigurasi dalam bahasa Ruby (format Cartfile) yang mendefinisikan dependensi proyek Carthage. Cartfile terletak di root proyek di samping .xcodeproj. Setiap baris Cartfile mendeskripsikan satu dependensi: sumber (URL Git, repositori GitHub) dan versi. Sintaksis mendukung penetapan versi melalui tag, commit dan branch.

# Dependensi dasar Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Directive github "Owner/Repo" — bentuk singkat untuk repositori GitHub. Carthage secara otomatis membangun URL dalam bentuk https://github.com/Owner/Repo.git. Untuk GitLab, Bitbucket dan host Git lainnya digunakan URL lengkap: git "https://gitlab.com/owner/repo.git". Operator versi: ~> 5.9 (versi apa pun dari 5.9 hingga 6.0 tidak termasuk 6.0), == 8.0.0 (versi tepat), >= 1.0 (versi minimal). Menghubungkan commit tertentu dapat dilakukan melalui github "owner/repo" "abc1234".

Contoh lengkap Cartfile

Carthage mendukung beberapa direktori untuk konfigurasi yang berbeda: Cartfile(utama), Cartfile.private (untuk dependensi internal yang tidak dipublikasikan) dan Cartfile.resolved (dihasilkan secara otomatis). Dependensi pribadi berguna untuk perpustakaan yang hanya digunakan dalam pembangunan Development, misalnya framework pengujian.

# Cartfile — dependensi utama
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

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

# Cabang pengembangan
github "marmelroy/PhoneNumberKit" "development"

github dan git — dua jenis sumber di Cartfile. Yang pertama ditujukan khusus untuk GitHub dan secara otomatis membentuk URL. Yang kedua — untuk repositori Git publik atau pribadi dengan URL lengkap. Versi dapat ditentukan dengan tag (== 2.1.1), rentang semantik (~> 5.9), nama branch ("development") atau hash commit ("a1b2c3d"). Penggunaan rentang semantik (~>) direkomendasikan untuk dependensi yang mengikuti SemVer — ini melindungi dari perubahan yang merusak saat pembaruan.

Cartfile.resolved dihasilkan secara otomatis setelah carthage update. Ini menetapkan versi yang tepat dari semua dependensi yang terinstal, termasuk yang transitif. File harus disimpan di Git — tanpanya perintah carthage bootstrap di mesin lain akan membangun perpustakaan dengan aturan yang sama, tetapi versinya mungkin berbeda. carthage outdated menampilkan daftar dependensi usang yang tersedia versi baru.

Instalasi dan konfigurasi Carthage

Carthage diinstal melalui Homebrew — manajer paket standar untuk macOS. Cara alternatif: instalasi dari penginstal .pkg siap pakai dari GitHub atau pembangunan dari kode sumber. Carthage memerlukan Xcode dengan Command Line Tools (termasuk xcodebuild), dan di Apple Silicon Mac — Rosetta 2 untuk beberapa dependensi lama.

# Menginstal Carthage melalui Homebrew
brew install carthage

# Memeriksa versi
carthage version

# Menginstal dari .pkg (jika Homebrew tidak tersedia)
# Unduh Carthage.pkg dari GitHub Releases dan instal secara manual

Setelah instalasi, inisialisasi proyek Carthage dimulai dengan membuat Cartfile di root proyek. Carthage tidak memiliki perintah init — file dibuat secara manual di editor teks. Setelah mengisi Cartfile dengan dependensi, pengembang menjalankan carthage bootstrap (jika Cartfile.resolved sudah ada) atau carthage update (instalasi awal atau pembaruan). Carthage mengkloning repositori, membangun framework dan menempatkannya di Carthage/Build/.

Pembaruan Carthage dilakukan melalui brew upgrade carthage. Versi diperiksa dengan perintah carthage version. Versi stabil terakhir pada pertengahan 2025 — 0.40 dengan dukungan bawaan untuk .xcframework, pembangunan paralel yang ditingkatkan dan dukungan penuh untuk Swift 6. Mulai versi 0.39 Carthage berhenti membangun .framework usang tanpa jembatan kompatibilitas — disarankan untuk secara eksplisit menentukan --use-xcframeworks.

# Memperbarui Carthage melalui Homebrew
brew upgrade carthage

# Instalasi versi tertentu
brew install carthage@0.39

# Instalasi ulang lengkap
brew uninstall carthage && brew install carthage

Perhatian: Carthage tidak membuat .xcworkspace dan tidak memodifikasi .xcodeproj. Berbeda dengan CocoaPods, Carthage memberikan kontrol penuh atas konfigurasi Xcode kepada pengembang. Ini berarti setelah menginstal dependensi, framework harus ditambahkan secara manual di Xcode (lihat bagian «Integrasi framework Carthage di Xcode»). Carthage juga memerlukan setiap dependensi untuk berisi proyek Xcode atau workspace dengan target framework — jika tidak, pembangunan akan berakhir dengan kesalahan.

Pembangunan framework: bootstrap dan update

Carthage menawarkan tiga perintah utama untuk bekerja dengan dependensi: bootstrap, update dan build. carthage bootstrap membangun dependensi dari Cartfile.resolved yang ada — direkomendasikan untuk lingkungan CI dan pengembang yang bergabung dengan proyek. carthage update memperbarui Cartfile.resolved ke versi terbaru (dengan mempertimbangkan batasan Cartfile) dan melakukan pembangunan. carthage build membangun semua dependensi yang ditentukan tanpa menyimpan versi.

# Instalasi awal (memperbarui versi)
carthage update --use-xcframeworks --platform iOS

# Pembangunan ulang berdasarkan versi tetap
carthage bootstrap --use-xcframeworks --platform iOS

# Membangun hanya satu dependensi
carthage build Alamofire --platform iOS

Bendera --use-xcframeworks memerintahkan Carthage untuk membangun .xcframework universal alih-alih .framework usang. Ini memastikan dukungan untuk simulator dan perangkat nyata, serta Apple Silicon Mac tanpa skrip tambahan. Bendera --platform iOS membatasi pembangunan ke satu platform iOS — ini secara signifikan mempercepat proses, terutama jika proyek menentukan perpustakaan lintas platform.

Carthage mendukung pembangunan paralel melalui bendera --cache-builds, yang menyimpan cache framework yang telah dibangun. Saat pembangunan ulang, Carthage memeriksa hash commit Git dan, jika kode tidak berubah, melewatkan kompilasi. Untuk server CI, disarankan untuk menyimpan cache direktori Carthage/Build/ dan ~/Library/Caches/carthage/. Carthage juga mendukung --verbose untuk logging terperinci dan --no-use-binaries untuk pembangunan paksa dari kode sumber (jika pengembang tidak mempercayai biner pra-bangun).

Integrasi framework Carthage di Xcode

Integrasi framework Carthage di Xcode dilakukan secara manual dalam empat langkah. Setelah menjalankan carthage update atau bootstrap, semua framework yang telah dibangun berada di Carthage/Build/iOS/ (atau platform yang sesuai). Pengembang membuka proyek Xcode, memilih target aplikasi dan menambahkan framework di General → Frameworks, Libraries, and Embedded Content. Untuk framework runtime (perpustakaan dinamis), harus memilih «Embed & Sign» — jika tidak, aplikasi akan crash saat dijalankan dengan kesalahan «dyld: Library not loaded».

Carthage untuk perpustakaan statis bekerja lebih sederhana — mereka tidak memerlukan fase embed, karena terhubung langsung ke file yang dapat dieksekusi aplikasi. Namun, Carthage secara default membangun framework dinamis (kecuali perpustakaan statis yang dikonfigurasi secara eksplisit). Untuk proyek yang penting untuk meminimalkan ukuran aplikasi, disarankan menggunakan tautan statis melalui pengaturan Xcode.

Langkah tambahan — menambahkan Input Files di Build Phase → Run Script. Carthage memerlukan skrip untuk menghapus artefak simulator dari framework yang telah dibangun (strip simulator architectures). Skrip ini diperlukan untuk pembangunan App Store:

# Run Script untuk 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 tidak memerlukan penggunaan .xcworkspace — semua dependensi sudah dibangun menjadi framework biner. Carthage bekerja langsung dengan .xcodeproj, berbeda dengan CocoaPods yang membuat workspace. Ini menyederhanakan kontrol versi dan konfigurasi CI, karena dependensi Carthage tidak mengubah konfigurasi proyek Xcode. Satu-satunya perubahan — penambahan framework ke target, yang dicatat di .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods dan Swift Package Manager (SPM) — tiga manajer dependensi utama dalam pengembangan iOS. Carthage dibedakan dengan pendekatan terdesentralisasi, CocoaPods menawarkan register terpusat, SPM — solusi bawaan dari Apple. Pilihan di antara mereka tergantung pada kebutuhan proyek, ukuran tim dan tingkat otomatisasi yang diperlukan.

Carthage dipilih untuk proyek yang memerlukan campur tangan minimal dalam konfigurasi Xcode dan kontrol penuh atas proses integrasi. Carthage ideal untuk perpustakaan terbuka dan framework, di mana penulis ingin memberikan pengguna kemampuan untuk membangun dependensi secara mandiri. Carthage juga populer di komunitas pengembang yang menghargai filosofi UNIX: setiap alat melakukan satu hal dengan baik. CocoaPods tetap menjadi standar untuk proyek perusahaan dengan puluhan dependensi di mana otomatisasi penting. SPM — pilihan untuk proyek baru, karena terintegrasi di Xcode dan aktif dikembangkan oleh Apple.

Migrasi antar manajer memerlukan pendekatan yang berbeda. Carthage → SPM: hapus framework dari Xcode, hapus Cartfile dan tambahkan Package Dependencies melalui File → Add Package Dependencies. Carthage → CocoaPods: hapus framework Carthage, buat Podfile, tambahkan dependensi dan jalankan pod init && pod install. Saat migrasi dari Carthage ke CocoaPods atau SPM, kebutuhan untuk memperbarui framework secara manual hilang — semua dependensi diperbarui dengan satu perintah. Carthage tetap relevan untuk proyek di mana penting untuk menghindari vendor lock-in dan mempertahankan transparansi pembangunan dependensi.

Masalah umum dan solusinya

Carthage — alat yang stabil, tetapi pengembang kadang-kadang menghadapi masalah umum, terutama saat membangun di server CI, memperbarui Xcode atau mengubah versi Swift. Sebagian besar masalah diselesaikan dengan membersihkan cache, mengonfigurasi --use-xcframeworks dengan benar dan memeriksa kesesuaian versi iOS minimal.

Kesalahan «The file manager returned an error» — muncul saat cache Carthage rusak atau konflik hak file. Solusi: hapus cache dengan perintah rm -rf ~/Library/Caches/carthage dan jalankan ulang carthage bootstrap. Juga membantu menghapus direktori Carthage/ di proyek dan membangun ulang. Di server CI, cache Carthage hanya boleh diperbarui saat Cartfile.resolved berubah.

Kesalahan «No such module» — framework tidak ditemukan di Xcode, meskipun pembangunan Carthage berhasil. Solusi: periksa jalur framework di General → Frameworks, Libraries, and Embedded Content. Framework harus berada di Carthage/Build/iOS/. Pastikan .xcframework telah ditambahkan dengan benar (seret lagi). Untuk framework dinamis, periksa Embed & Sign. Jika kesalahan tetap ada — tambahkan FRAMEWORK_SEARCH_PATHS di Build Settings.

Kesalahan pembangunan karena ketidakcocokan Swift — perpustakaan dibangun untuk versi Swift yang berbeda dari proyek. Solusi: gunakan carthage update --no-use-binaries untuk pembangunan paksa dari kode sumber dengan versi Swift yang sama. Jika perpustakaan tidak dapat dikompilasi di bawah versi saat ini — gunakan .xcconfig untuk menentukan versi Swift atau fork perpustakaan. Mulai Carthage 0.39, --use-xcframeworks secara otomatis menyertakan versi Swift yang benar ke dalam biner.

Masalah pembangunan CI — Carthage di CI memerlukan konfigurasi caching yang benar. Solusi: cache Carthage/Build/ dan ~/Library/Caches/carthage/. Gunakan carthage bootstrap --use-xcframeworks --platform iOS alih-alih update di CI agar tidak mengubah versi. Untuk GitHub Actions, tersedia action Carthage resmi. Untuk Jenkins — plugin CarthageBuild. Carthage bisa crash di macOS tanpa GUI — solusi: instal brew install xcode-build-server atau tambahkan kunci -UseModernBuildSystem=NO.