Carthage: какво е, децентрализиран мениджър на зависимости

Какво е Carthage?

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

Архитектурата на Carthage включва три компонента: CLI инструментът carthage, конфигурационният файл Cartfile и директорията Carthage/Build/ с изградените frameworks. Принципната разлика на Carthage от CocoaPods — липсата на автоматична модификация на .xcodeproj. Carthage не създава .xcworkspace, не конфигурира флагове на компилатора и не генерира Pods.xcconfig. Разработчикът сам добавя frameworks към проекта чрез Xcode, което дава пълен контрол върху процеса на интеграция.

Carthage използва паралелно изграждане на зависимости, което значително ускорява процеса на многоядрени процесори. Всяка зависимост се изгражда като отделна цел и 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 за изграждане на framework. Carthage определя типа на Xcode проекта (framework, dynamic framework, статична библиотека) автоматично по схемата на изграждане. Ако проектът съдържа няколко схеми, Carthage използва схемата по подразбиране (първата по азбучен ред). След изграждането Carthage копира готовия framework в Carthage/Build/ и създава файла Cartfile.resolved с фиксиране на точните версии. Carthage поддържа кеширане на изградените frameworks — повторно изграждане без промени на зависимостите не се изпълнява.

Транзитивните зависимости в Carthage се обработват чрез Cartfile.resolved: Carthage изгражда граф на всички необходими зависимости и ги изгражда в правилния ред. Ако две библиотеки зависят от една и съща библиотека на трета страна, Carthage я изгражда веднъж и я използва и за двете. Carthage уведомлява за грешки при изграждане с посочване на конкретната цел и причина — това опростява диагностицирането на проблеми.

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 изграждане, например тестови frameworks.

# 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

# Клон за разработка
github "marmelroy/PhoneNumberKit" "development"

github и git — два типа източници в Cartfile. Първият е предназначен изключително за GitHub и автоматично формира URL. Вторият — за всякакви публични или частни Git хранилища с пълен URL. Версията може да бъде указана с tag (== 2.1.1), семантичен диапазон (~> 5.9), име на branch ("development") или hash на commit ("a1b2c3d"). Използването на семантични диапазони (~>) се препоръчва за зависимости, които следват SemVer — това предпазва от разрушителни промени при актуализиране.

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 клонира хранилищата, изгражда frameworks и ги поставя в Carthage/Build/.

Актуализиране на Carthage се извършва чрез brew upgrade carthage. Версията се проверява с командата carthage version. Последната стабилна версия към средата на 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 на разработчика. Това означава, че след инсталиране на зависимостите трябва ръчно да добавите frameworks в Xcode (вижте раздела «Интеграция на Carthage frameworks в Xcode»). Carthage също изисква всяка зависимост да съдържа Xcode проект или workspace с framework цел — в противен случай изграждането ще завърши с грешка.

Изграждане на frameworks: 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, който кешира вече изградените frameworks. При повторно изграждане Carthage проверява hash-а на Git commit и, ако кодът не се е променил, пропуска компилацията. За CI сървъри се препоръчва кеширане на директорията Carthage/Build/ и ~/Library/Caches/carthage/. Carthage също поддържа --verbose за подробно логване и --no-use-binaries за принудително изграждане от изходен код (ако разработчикът не вярва на предварително изградените бинарни файлове).

Интеграция на Carthage frameworks в Xcode

Интеграция на Carthage frameworks в Xcode се извършва ръчно в четири стъпки. След изпълнение на carthage update или bootstrap всички изградени frameworks се намират в Carthage/Build/iOS/ (или съответната платформа). Разработчикът отваря Xcode проекта, избира целта на приложението и добавя frameworks в General → Frameworks, Libraries, and Embedded Content. За runtime frameworks (динамични библиотеки) трябва да се избере «Embed & Sign» — в противен случай приложението ще се срине при стартиране с грешка «dyld: Library not loaded».

Carthage за статични библиотеки работи по-просто — те не изискват embed фаза, тъй като се свързват директно към изпълнимия файл на приложението. Въпреки това, Carthage по подразбиране изгражда динамични frameworks (освен изрично конфигурирани статични библиотеки). За проекти, където е важно минимизиране на размера на приложението, се препоръчва използване на статично свързване чрез настройките на Xcode.

Допълнителна стъпка — добавяне на Input Files в Build Phase → Run Script. Carthage изисква скрипт за премахване на артефакти от симулатор от изградения framework (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 — всички зависимости са вече изградени в бинарни frameworks. Carthage работи директно с .xcodeproj, за разлика от CocoaPods, който създава workspace. Това опростява контрола на версиите и конфигурирането на CI, тъй като Carthage зависимостите не променят конфигурацията на Xcode проекта. Единствената промяна — добавяне на frameworks към целта, което се записва в .pbxproj.

Carthage vs CocoaPods vs Swift Package Manager

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

Carthage се избира за проекти, където е необходима минимална намеса в конфигурацията на Xcode и пълен контрол върху процеса на интеграция. Carthage е идеален за отворени библиотеки и frameworks, където авторът иска да предостави на потребителите възможност да изграждат зависимости самостоятелно. Carthage е популярен и в общността на разработчици, които ценят UNIX философията: всеки инструмент прави едно нещо добре. CocoaPods остава стандарт за корпоративни проекти с десетки зависимости, където автоматизацията е важна. SPM — избор за нови проекти, тъй като е вграден в Xcode и се развива активно от Apple.

Миграция между мениджърите изисква различен подход. Carthage → SPM: премахнете frameworks от Xcode, изтрийте Cartfile и добавете Package Dependencies чрез File → Add Package Dependencies. Carthage → CocoaPods: премахнете Carthage frameworks, създайте Podfile, добавете зависимости и изпълнете pod init && pod install. При миграция от Carthage към CocoaPods или SPM изчезва необходимостта от ръчно актуализиране на frameworks — всички зависимости се актуализират с една команда. 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» — framework не е намерен в Xcode, въпреки че изграждането на Carthage е успешно. Решение: проверете пътя на framework в General → Frameworks, Libraries, and Embedded Content. Framework трябва да бъде в Carthage/Build/iOS/. Уверете се, че .xcframework е добавен правилно (плъзнете отново). За динамични frameworks проверете 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 action. За Jenkins — приставката CarthageBuild. Carthage може да се срине на macOS без GUI — решение: инсталирайте brew install xcode-build-server или добавете ключа -UseModernBuildSystem=NO.