Carthage: шта је то, децентрализовани менаџер зависности

Шта је Carthage?

Carthage — менаџер зависности са децентрализованом архитектуром, направљен 2014. године од стране програмера из Swift заједнице. Carthage не користи централни регистар спецификација — свака библиотека се повезује директно из Git репозиторијума преко URL-а или имена на GitHub-у. Carthage преузима изворни код, гради га у бинарни фрејмворк (.xcframework или .framework) и пружа програмеру готов артефакт за ручну интеграцију у Xcode пројекат.

Архитектура Carthage-а укључује три компоненте: CLI алат carthage, конфигурациони фајл Cartfile и директоријум Carthage/Build/ са изграђеним фрејмворцима. Принципијелна разлика Carthage-а у односу на CocoaPods — одсуство аутоматске модификације .xcodeproj. Carthage не ствара .xcworkspace, не подешава флагове компајлера и не генерише Pods.xcconfig. Програмер самостално додаје фрејмворке у пројекат кроз Xcode, што даје потпуну контролу над процесом интеграције.

Carthage користи паралелну изградњу зависности, што значајно убрзава процес на вишејезгарним процесорима. Свака зависност се гради као посебан target, а Carthage аутоматски решава граф транзитивних зависности, градећи их у исправном редоследу. Према бенчмарковима заједнице, Carthage гради 15–20 зависности у просеку за 30–60 секунди на модерним Mac рачунарима, што је брже од CocoaPods-а за пројекте са великим бројем библиотека. Carthage подржава све Apple платформе: iOS, macOS, watchOS и tvOS, а од верзије 0.38+ — изградњу универзалних .xcframework за подршку симулаторима и Apple Silicon уређајима.

Како Carthage ради

Carthage клонира Git репозиторијум сваке зависности, прелази на наведену верзију (tag, commit или branch) и покреће xcodebuild за изградњу фрејмворка. Carthage одређује тип Xcode пројекта (фрејмворк, dynamic framework, статичка библиотека) аутоматски према шеми изградње. Ако пројекат садржи више шема, Carthage користи подразумевану шему (прву по абецедном реду). Након изградње, Carthage копира готов фрејмворк у Carthage/Build/ и креира фајл Cartfile.resolved са фиксацијом тачних верзија. Carthage подржава кеширање изграђених фрејмворка — поновна изградња без промена зависности се не извршава.

Транзитивне зависности у Carthage-у се обрађују кроз Cartfile.resolved: Carthage гради граф свих потребних зависности и гради их у исправном редоследу. Ако две библиотеке зависе од исте треће библиотеке, Carthage је гради једном и користи за обе. Carthage обавештава о грешкама изградње са навођењем конкретног target-а и разлога — ово поједностављује дијагностику проблема.

Cartfile: структура, синтакса и примери

Cartfile — конфигурациони фајл на Ruby језику (формат Cartfile) који дефинише зависности Carthage пројекта. Cartfile се налази у корену пројекта поред .xcodeproj. Сваки ред Cartfile-а описује једну зависност: извор (Git-URL, GitHub репозиторијум) и верзију. Синтакса подржава фиксацију верзија кроз tag-ове, commit-ове и branch-еве.

# Базовые зависимости Carthage
github "Alamofire/Alamofire" ~> 5.9
github "SnapKit/SnapKit" ~> 5.7
github "onevcat/Kingfisher" == 8.0.0

Директива github "Owner/Repo" — скраћена форма за GitHub репозиторијуме. Carthage аутоматски гради URL облика https://github.com/Owner/Repo.git. За GitLab, Bitbucket и друге Git хостинге користи се пуни URL: git "https://gitlab.com/owner/repo.git". Оператори верзија: ~> 5.9 (било која верзија од 5.9 до 6.0 искључујући 6.0), == 8.0.0 (тачна верзија), >= 1.0 (минимална верзија). Повезивање конкретног commit-а може се извршити кроз github "owner/repo" "abc1234".

Потпуни пример Cartfile-а

Carthage подржава неколико директоријума за различите конфигурације: Cartfile (главни), Cartfile.private (за интерне зависности које се не објављују) и Cartfile.resolved (генерише се аутоматски). Приватне зависности су корисне за библиотеке које се користе само у Development изградњи, на пример тестних фрејмворка.

# Cartfile — основные зависимости
github "Alamofire/Alamofire" ~> 5.9
github "SwiftyJSON/SwiftyJSON" ~> 4.0
github "realm/realm-swift" ~> 10.0

# Полный URL для GitLab
git "https://gitlab.com/company/internal-lib.git" == 2.1.1

# Развојни branch
github "marmelroy/PhoneNumberKit" "development"

github и git — два типа извора у Cartfile-у. Први је намењен искључиво за GitHub и аутоматски формира URL. Други — за било које јавне или приватне Git репозиторијуме са комплетним URL-ом. Верзија може бити наведена tag-ом (== 2.1.1), семантичким опсегом (~> 5.9), именом branch-а ("development") или хешом commit-а ("a1b2c3d"). Коришћење семантичких опсега (~>) се препоручује за зависности које прате SemVer — ово штити од breaking changes приликом ажурирања.

Cartfile.resolved се генерише аутоматски након carthage update. Он фиксира тачне верзије свих инсталираних зависности, укључујући транзитивне. Фајл треба чувати у Git-у — без њега команда carthage bootstrap на другом рачунару ће изградити библиотеке по истим правилима, али верзије могу да се разликују. carthage outdated приказује листу застарелих зависности за које су доступне нове верзије.

Инсталација и подешавање Carthage-а

Carthage се инсталира преко Homebrew-а — стандардног менаџера пакета за macOS. Алтернативни начини: инсталација из готовог .pkg инсталатора са GitHub-а или изградња из изворног кода. Carthage захтева Xcode са Command Line Tools (укључујући xcodebuild), а на Apple Silicon Mac-у — Rosetta 2 за неке старије зависности.

# Установка Carthage через Homebrew
brew install carthage

# Провера верзије
carthage version

# Установка из .pkg (если Homebrew недоступен)
# Скачать Carthage.pkg с GitHub Releases и установить вручную

Након инсталације, иницијализација Carthage пројекта почиње креирањем Cartfile-а у корену пројекта. Carthage нема команду init — фајл се креира ручно у текст едитору. Након попуњавања Cartfile-а зависностима, програмер покреће carthage bootstrap (ако Cartfile.resolved већ постоји) или carthage update (почетна инсталација или ажурирање). Carthage клонира репозиторијуме, гради фрејмворке и смешта их у Carthage/Build/.

Ажурирање Carthage-а се врши кроз brew upgrade carthage. Верзија се проверава командом carthage version. Последња стабилна верзија на mid-2025 — 0.40 са подршком за .xcframework подразумевано, побољшаном паралелном изградњом и потпуном подршком за Swift 6. Почев од верзије 0.39 Carthage је престао да гради застареле .framework-ове без моста компатибилности — препоручује се експлицитно навођење --use-xcframeworks.

# Обновление Carthage через Homebrew
brew upgrade carthage

# Инсталација одређене верзије
brew install carthage@0.39

# Потпуна поновна инсталација
brew uninstall carthage && brew install carthage

Напомена: Carthage не креира .xcworkspace и не мења .xcodeproj. За разлику од CocoaPods-а, Carthage оставља потпуну контролу над конфигурацијом Xcode-а програмеру. То значи да након инсталације зависности треба ручно додати фрејмворке у Xcode (погледајте одељак «Интеграција Carthage фрејмворка у Xcode»). Carthage такође захтева да свака зависност садржи Xcode пројекат или workspace са фрејмворк target-ом — иначе ће се изградња завршити грешком.

Изградња фрејмворка: bootstrap и update

Carthage нуди три главне команде за рад са зависностима: bootstrap, update и build. carthage bootstrap гради зависности из постојећег Cartfile.resolved-а — препоручује се за CI окружења и програмере који се придружују пројекту. carthage update ажурира Cartfile.resolved до најновијих верзија (узимајући у обзир ограничења Cartfile-а) и извршава изградњу. carthage build гради све наведене зависности без чувања верзија.

# Почетна инсталација (ажурира верзије)
carthage update --use-xcframeworks --platform iOS

# Поновна изградња по фиксним верзијама
carthage bootstrap --use-xcframeworks --platform iOS

# Изградња само једне зависности
carthage build Alamofire --platform iOS

Застава --use-xcframeworks налаже Carthage-у да гради универзалне .xcframework-е уместо застарелих .framework-а. Ово обезбеђује подршку и за симулатор и за прави уређај, као и за Apple Silicon Mac без додатних скрипти. Застава --platform iOS ограничава изградњу на једну платформу iOS — ово значајно убрзава процес, посебно ако су у пројекту наведене вишеплатформске библиотеке.

Carthage подржава паралелну изградњу кроз заставу --cache-builds, која кешира већ изграђене фрејмворке. При поновној изградњи Carthage проверава хеш Git commit-а и, ако се код није променио, прескаче компајлацију. За CI сервере се препоручује кеширање директоријума Carthage/Build/ и ~/Library/Caches/carthage/. Carthage такође подржава --verbose за детаљно логирање и --no-use-binaries за принудну изградњу из изворног кода (ако програмер не верује унапред изграђеним бинарним датотекама).

Интеграција Carthage фрејмворка у Xcode

Интеграција Carthage фрејмворка у Xcode се изводи ручно у четири корака. Након извршења carthage update или bootstrap сви изграђени фрејмворци се налазе у Carthage/Build/iOS/ (или одговарајућој платформи). Програмер отвара Xcode пројекат, бира target апликације и додаје фрејмворке у General → Frameworks, Libraries, and Embedded Content. За runtime фрејмворке (динамичке библиотеке) потребно је изабрати «Embed & Sign» — иначе ће апликација пасти при покретању са грешком «dyld: Library not loaded».

Carthage за статичке библиотеке ради једноставније — one не захтевају embed фазу, јер се линкују директно у извршни фајл апликације. Међутим, Carthage подразумевано гради динамичке фрејмворке (осим експлицитно подешених статичких библиотека). За пројекте где је важно минимизирати величину апликације, препоручује се коришћење статичког линковања кроз подешавања Xcode-а.

Додатни корак — додавање Input Files у Build Phase → Run Script. Carthage захтева скрипту за уклањање артефаката симулатора из изграђеног фрејмворка (strip simulator architectures). Ова скрипта је неопходна за App Store изградње:

# Run Script для 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-а — све зависности су већ изграђене у бинарне фрејмворке. Carthage ради директно са .xcodeproj-ом, за разлику од CocoaPods-а који креира workspace. Ово поједностављује контролу верзија и подешавање CI-ја, јер Carthage зависности не мењају конфигурацију Xcode пројекта. Једина измена — додавање фрејмворка у target, која се бележи у .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

Carthage, CocoaPods и Swift Package Manager (SPM) — три главна менаџера зависности у iOS развоју. Carthage се одликује децентрализованим приступом, CocoaPods нуди централизовани регистар, SPM — уграђено решење од Apple-а. Избор између њих зависи од захтева пројекта, величине тима и потребног нивоа аутоматизације.

Carthage се бира за пројекте где је потребна минимална интервенција у конфигурацију Xcode-а и потпуна контрола над процесом интеграције. Carthage је идеалан за отворене библиотеке и фрејмворке, где аутор жели да пружи корисницима могућност да сами граде зависности. Carthage је такође популаран у заједници програмера који цене UNIX филозофију: сваки алат ради једну ствар добро. CocoaPods остаје стандард за корпоративне пројекте са десетинама зависности, где је важна аутоматизација. SPM — избор за нове пројекте, јер је уграђен у Xcode и активно га развија Apple.

Миграција између менаџера захтева различит приступ. Carthage → SPM: уклонити фрејмворке из Xcode-а, обрисати Cartfile и додати Package Dependencies кроз File → Add Package Dependencies. Carthage → CocoaPods: уклонити Carthage фрејмворке, креирати Podfile, додати зависности и извршити pod init && pod install. При миграцији са Carthage-а на CocoaPods или SPM нестаје потреба за ручним ажурирањем фрејмворка — све зависности се ажурирају једном командом. Carthage остаје релевантан за пројекте где је важно избећи vendor lock-in и задржати транспарентност изградње зависности.

Чести проблеми и њихово решавање

Carthage — стабилан алат, али програмери повремено наилазе на типичне проблеме, посебно при изградњи на CI серверима, ажурирању Xcode-а или промени верзија Swift-а. Већина проблема се решава чишћењем кеша, правилним подешавањем --use-xcframeworks и провером усклађености минималне iOS верзије.

Грешка «The file manager returned an error» — настаје при оштећењу Carthage кеша или конфликту права приступа фајловима. Решење: уклонити кеш командом rm -rf ~/Library/Caches/carthage и поново покренути carthage bootstrap. Такође помаже уклањање директоријума Carthage/ у пројекту и поновна изградња. На CI серверима Carthage кеш треба ажурирати само при промени Cartfile.resolved-а.

Грешка «No such module» — фрејмворк није пронађен у Xcode-у, иако је Carthage изградња успешно завршена. Решење: проверити путању фрејмворка у General → Frameworks, Libraries, and Embedded Content. Фрејмворк треба да буде у Carthage/Build/iOS/. Уверити се да је .xcframework додат исправно (превући поново). За динамичке фрејмворке проверити Embed & Sign. Ако грешка остане — додати FRAMEWORK_SEARCH_PATHS у Build Settings.

Грешка при изградњи због некомпатибилности Swift-а — библиотека је изграђена за другу верзију Swift-а него пројекат. Решење: користити carthage update --no-use-binaries за принудну изградњу из изворног кода истом верзијом Swift-а. Ако се библиотека не компајлира под тренутном верзијом — користити .xcconfig за навођење Swift верзије или форковати библиотеку. Почев од Carthage 0.39, --use-xcframeworks аутоматски укључује исправну Swift верзију у бинарну датотеку.

Проблеми са CI изградњом — Carthage на CI-ју захтева правилно подешавање кеширања. Решење: кеширати Carthage/Build/ и ~/Library/Caches/carthage/. Користити carthage bootstrap --use-xcframeworks --platform iOS уместо update на CI-ју, да не би мењали верзије. За GitHub Actions доступна је званична Carthage акција. За Jenkins — додатак CarthageBuild. Carthage може пасти на macOS-у без GUI-ја — решење: инсталирати brew install xcode-build-server или додати кључ -UseModernBuildSystem=NO.