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 використовує паралельну збірку залежностей, що значно прискорює процес на багатоядерних процесорах. Кожна залежність збирається як окремий таргет, і Carthage автоматично вирішує граф транзитивних залежностей, збираючи їх у правильному порядку. За результатами бенчмарків спільноти, Carthage збирає 15–20 залежностей у середньому за 30–60 секунд на сучасних Mac, що швидше за CocoaPods для проєктів з великою кількістю бібліотек. Carthage підтримує всі платформи Apple: iOS, macOS, watchOS і tvOS, а з версії 0.38+ — збірку універсальних .xcframework для підтримки симуляторів і пристроїв Apple Silicon.

Як працює Carthage

Carthage клонує Git-репозиторій кожної залежності, перемикається на вказану версію (тег, коміт або гілку) та запускає xcodebuild для збірки фреймворка. Carthage визначає тип Xcode-проєкту (фреймворк, dynamic framework, статична бібліотека) автоматично за схемою збірки. Якщо проєкт містить кілька схем, Carthage використовує схему за замовчуванням (першу в алфавітному порядку). Після збірки Carthage копіює готовий фреймворк у Carthage/Build/ і створює файл Cartfile.resolved із фіксацією точних версій. Carthage підтримує кешування зібраних фреймворків — повторна збірка без змін залежностей не виконується.

Транзитивні залежності в Carthage обробляються через Cartfile.resolved: Carthage будує граф усіх необхідних залежностей і збирає їх у правильному порядку. Якщо дві бібліотеки залежать від однієї і тієї ж сторонньої бібліотеки, Carthage збирає її один раз і використовує для обох. Carthage повідомляє про помилки збірки із зазначенням конкретного таргету та причини — це спрощує діагностику проблем.

Cartfile: структура, синтаксис та приклади

Cartfile — конфігураційний файл на мові Ruby (формат Cartfile), що визначає залежності Carthage-проєкту. Cartfile розташовується в корені проєкту поруч із .xcodeproj. Кожен рядок Cartfile описує одну залежність: джерело (Git-URL, GitHub-репозиторій) та версію. Синтаксис підтримує фіксацію версій через теги, коміти та гілки.

# Базовые зависимости 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 (мінімальна версія). Підключити конкретний коміт можна через github "owner/repo" "abc1234".

Повний приклад Cartfile

Carthage підтримує кілька директорій для різних конфігурацій: Cartfile (основний), Cartfile.private (для внутрішніх залежностей, що не публікуються) і Cartfile.resolved (генерується автоматично). Private-залежності корисні для бібліотек, що використовуються тільки в 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

# Гілка розробки
github "marmelroy/PhoneNumberKit" "development"

github і git — два типи джерел у Cartfile. Перший призначений виключно для GitHub і автоматично формує URL. Другий — для будь-яких публічних або приватних Git-репозиторіїв із повним URL. Версія може бути вказана тегом (== 2.1.1), семантичним діапазоном (~> 5.9), ім'ям гілки ("development") або хешем коміту ("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 для деяких legacy-залежностей.

# Установка 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 із фреймворк-таргетом — інакше збірка завершиться помилкою.

Збірка фреймворків: 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-коміту і, якщо код не змінився, пропускає компіляцію. Для CI-серверів рекомендується кешувати директорію Carthage/Build/ і ~/Library/Caches/carthage/. Carthage також підтримує --verbose для детального логування та --no-use-binaries для примусової збірки з вихідників (якщо розробник не довіряє попередньо зібраним бінарникам).

Інтеграція Carthage-фреймворків у Xcode

Інтеграція Carthage-фреймворків у Xcode виконується вручну в чотири кроки. Після виконання carthage update або bootstrap всі зібрані фреймворки знаходяться в Carthage/Build/iOS/ (або відповідній платформі). Розробник відкриває Xcode-проєкт, вибирає таргет додатка та додає фреймворки в General → Frameworks, Libraries, and Embedded Content. Для рантайм-фреймворків (динамічних бібліотек) необхідно вибрати «Embed & Sign» — інакше додаток впаде при запуску з помилкою «dyld: Library not loaded».

Carthage для статичних бібліотек працює простіше — вони не вимагають 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-проєкту. Єдина зміна — додавання фреймворків у таргет, яке фіксується в .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 доступна офіційна action Carthage. Для Jenkins — плагін CarthageBuild. Carthage може падати на macOS без GUI — вирішення: встановити brew install xcode-build-server або додати ключ -UseModernBuildSystem=NO.