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 использует схему по умолчанию (первую в alphabetical порядке). После сборки 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.