Carthage
0.40.0
Carthage задуман как самый простой способ добавления фреймворков в ваше приложение Cocoa.
Carthage создает ваши зависимости и предоставляет вам двоичные платформы, но вы сохраняете полный контроль над структурой и настройкой вашего проекта. Carthage не изменяет автоматически файлы проекта или настройки сборки.
Загрузите Carthage, запустив brew install carthage или выбрав другой метод установки.
Создайте файл Cartfile в том же каталоге, где находится ваш .xcodeproj или .xcworkspace
Перечислите нужные зависимости в Cartfile, например:
github "Alamofire/Alamofire" ~> 5.5
Запустите carthage update --use-xcframeworks
Файл Cartfile.resolved и каталог Carthage появятся в том же каталоге, где находится ваш .xcodeproj или .xcworkspace
Перетащите собранные пакеты .xcframework из Carthage/Build в раздел «Frameworks and Libraries» проекта Xcode вашего приложения.
Если вы используете Carthage для приложения, выберите «Встроить и подписать», в противном случае — «Не встраивать».
Подробное руководство можно найти в разделе Добавление платформ в приложение.
Существует несколько вариантов установки Carthage:
Установщик: загрузите и запустите файл Carthage.pkg последней версии, затем следуйте инструкциям на экране. Если вы устанавливаете пакет через CLI, вам может потребоваться сначала запустить sudo chown -R $(whoami) /usr/local .
Homebrew: вы можете использовать Homebrew и установить инструмент carthage в свою систему, просто запустив brew update и brew install carthage . (примечание: если вы ранее установили двоичную версию Carthage, вам следует удалить /Library/Frameworks/CarthageKit.framework ).
MacPorts: вы можете использовать MacPorts и установить инструмент carthage в своей системе, просто запустив sudo port selfupdate и sudo port install carthage . (примечание: если вы ранее установили двоичную версию Carthage, вам следует удалить /Library/Frameworks/CarthageKit.framework ).
Из источника: Если вы хотите запустить последнюю версию разработки (которая может быть крайне нестабильной или несовместимой), просто клонируйте master ветку репозитория, а затем запустите make install . Требуется Xcode 10.0 (Swift 4.2).
После установки Carthage вы можете начать добавлять фреймворки в свой проект. Обратите внимание, что Carthage поддерживает только динамические платформы, которые доступны только в iOS 8 или более поздних версиях (или в любой версии OS X).
carthage update --use-xcframeworks . Это позволит загрузить зависимости в папку Carthage/Checkouts и собрать каждую из них или загрузить предварительно скомпилированный XCFramework.Мы рекомендуем использовать XCFrameworks начиная с версии 0.37.0 (январь 2021 г.) и требуем XCFrameworks при сборке на Apple Silicon Mac. Переход от пакетов дискретных фреймворков к XCFrameworks требует внесения некоторых изменений в ваш проект:
Carthage/Build чтобы удалить все существующие пакеты фреймворка.carthage build --use-xcframeworks . Любые другие аргументы, которые вы создаете, могут быть предоставлены как обычно.carthage copy-frameworks , если он присутствует.Несовместимость с Xcode 12+ : мультиархитектурные платформы не поддерживаются при сборке пакетов фреймворка в Xcode 12 и выше. Предпочитайте сборку с помощью XCFrameworks. Если вам нужно создать отдельные пакеты инфраструктуры, используйте обходной файл xcconfig.
carthage update --platform macOS . Это позволит загрузить зависимости в папку Carthage/Checkouts и собрать каждую из них или загрузить предварительно скомпилированную структуру.Кроме того, вам потребуется скопировать символы отладки для отладки и создания отчетов о сбоях в OS X.
Создайте файл Cartfile, в котором перечислены платформы, которые вы хотели бы использовать в своем проекте.
Запустите carthage update . При этом зависимости будут загружены в папку Carthage/Checkouts, а затем собрана каждая из них или загружена предварительно скомпилированная платформа.
Откройте вкладку « Общие настройки» целей вашего приложения. Для Xcode 11.0 и более поздних версий в разделе «Рамки, библиотеки и встроенный контент» перетащите каждую платформу, которую вы хотите использовать, из папки Carthage/Build на диске. Затем в разделе «Встроить» выберите «Не вставлять» в раскрывающемся меню для каждого добавленного элемента. Для Xcode 10.x и более ранних версий в разделе «Связанные платформы и библиотеки» перетащите каждую платформу, которую вы хотите использовать, из папки Carthage/Build на диске.
На вкладке настроек « Фазы сборки » целевых объектов вашего приложения щелкните значок «+» и выберите «Новая фаза запуска сценария» . Создайте сценарий запуска, в котором укажите свою оболочку (например: /bin/sh ), добавьте следующее содержимое в область сценария под оболочкой:
/usr/local/bin/carthage copy-frameworks Создайте файл с именем input.xcfilelist и файл с именем output.xcfilelist
Добавьте пути к платформам, которые вы хотите использовать, в свой input.xcfilelist . Например:
$(SRCROOT)/Carthage/Build/iOS/Result.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveSwift.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework
Добавьте пути к скопированным фреймворкам в output.xcfilelist . Например:
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Result.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveSwift.framework
$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveCocoa.framework
Если выходные файлы указаны рядом с входными файлами, Xcode нужно запускать сценарий только тогда, когда входные файлы изменились или выходные файлы отсутствуют. Это означает, что грязные сборки будут выполняться быстрее, если вы не пересобирали фреймворки с помощью Carthage.
Добавьте input.xcfilelist в раздел «Списки входных файлов» на этапе запуска сценария Carthage.
Добавьте файл output.xcfilelist в раздел «Списки выходных файлов» на этапе запуска сценария Carthage.
Этот сценарий устраняет ошибку отправки в App Store, вызванную универсальными двоичными файлами, и гарантирует, что необходимые файлы, связанные с бит-кодом, и dSYM копируются при архивировании.
С помощью отладочной информации, скопированной в каталог встроенных продуктов, Xcode сможет обозначать трассировку стека всякий раз, когда вы останавливаетесь на точке останова. Это также позволит вам выполнять сторонний код в отладчике.
При архивировании вашего приложения для отправки в App Store или TestFlight Xcode также скопирует эти файлы в подкаталог dSYMs пакета .xcarchive вашего приложения.
Попутно Карфаген создаст несколько артефактов сборки. Самым важным из них является файл Cartfile.resolved, в котором перечислены версии, фактически созданные для каждой платформы. Обязательно зафиксируйте свой Cartfile.resolved , потому что всем, кто использует проект, этот файл понадобится для создания тех же версий платформы.
Вы можете добавить этап «Выполнить сценарий», чтобы автоматически предупреждать вас, когда одна из ваших зависимостей устарела.
Build Phases » целевых объектов вашего приложения щелкните значок + и выберите New Run Script Phase . Создайте сценарий запуска, в котором укажите свою оболочку (например: /bin/sh ), добавьте следующее содержимое в область сценария под оболочкой: /usr/local/bin/carthage outdated --xcode-warnings 2> /dev/nullCarthage проверит, что загруженные платформы Swift (и смешанные Objective-C/Swift) созданы с использованием той же версии Swift, которая используется локально. Если обнаружится несоответствие версий, Carthage продолжит сборку платформы из исходного кода. Если фреймворк не может быть построен из исходного кода, Карфаген потерпит неудачу.
Поскольку Carthage использует выходные данные xcrun swift --version для определения локальной версии Swift, обязательно запускайте команды Carthage с помощью той цепочки инструментов Swift, которую вы собираетесь использовать. Для многих случаев использования ничего дополнительного не требуется. Однако, например, если вы создаете проект Swift 2.3 с использованием Xcode 8.x, одним из подходов к указанию swift по умолчанию для carthage bootstrap является использование следующей команды:
TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 carthage bootstrap
После того, как вы выполнили вышеуказанные шаги и внесли свои изменения, другим пользователям проекта нужно будет только получить репозиторий и запустить carthage bootstrap , чтобы начать работу с добавленными вами платформами.
Использование Carthage для зависимостей любой произвольной цели очень похоже на использование Carthage для приложения. Основное различие заключается в том, как на самом деле фреймворки настраиваются и связываются в Xcode.
Поскольку в целях модульного тестирования отсутствует раздел «Связанные платформы и библиотеки» на вкладке «Общие настройки», вместо этого необходимо перетащить построенные платформы на этап сборки «Связывание двоичных файлов с библиотеками» .
В цели «Тест» на вкладке «Настройки сборки» добавьте @loader_path/Frameworks в пути поиска пути выполнения, если он еще не присутствует.
В редких случаях вам может потребоваться также скопировать каждую зависимость в продукт сборки (например, чтобы внедрить зависимости во внешнюю структуру или убедиться, что зависимости присутствуют в тестовом пакете). Для этого создайте новую фазу сборки Copy Files с назначением Frameworks , а затем добавьте туда ссылку на платформу. Не следует использовать команду carthage copy-frameworks поскольку для тестовых пакетов не требуется удаление платформ, а одновременный запуск экземпляров copy-frameworks (с включенными параллельными сборками) не поддерживается.
Если вы изменили свой Cartfile или хотите обновить каждую платформу до новейших версий (с учетом указанных вами требований), просто запустите команду carthage update еще раз.
Если вы хотите обновить только одну или конкретные зависимости, передайте их в виде списка, разделенного пробелами, команде update . например
carthage update Box
или
carthage update Box Result
Переписана логика обновления фреймворков с целью увеличения скорости и уменьшения использования памяти. В настоящее время это опциональная функция. Его можно использовать, передав --new-resolver в команду обновления, например:
carthage update --new-resolver Box
Если у вас возникли проблемы с производительностью во время обновлений, попробуйте новый преобразователь.
Если фреймворк, который вы хотите добавить в свой проект, имеет зависимости, явно перечисленные в Cartfile, Carthage автоматически извлечет их для вас. Затем вам придется перетащить их в свой проект из папки Carthage/Build.
Если встроенная платформа в вашем проекте имеет зависимости от других платформ, вы должны связать их с целью приложения (даже если цель приложения не зависит от этих платформ и никогда не использует их).
По умолчанию Carthage напрямую извлекает исходные файлы зависимостей в папку вашего проекта, оставляя вам возможность зафиксировать или игнорировать их по вашему выбору. Если вместо этого вы хотите, чтобы зависимости были доступны в виде подмодулей Git (возможно, чтобы вы могли фиксировать и отправлять изменения внутри них), вы можете запустить carthage update или carthage checkout с флагом --use-submodules .
При таком запуске Carthage будет записывать файлы .gitmodules и .git/config вашего репозитория и автоматически обновлять подмодули при изменении версий зависимостей.
Если вы хотите работать со своими зависимостями во время разработки и хотите, чтобы они автоматически перестраивались при сборке родительского проекта, вы можете добавить этап сборки Run Script, который вызывает Carthage следующим образом:
/usr/local/bin/carthage build --platform " $PLATFORM_NAME " --project-directory " $SRCROOT "Обратите внимание, что перед этим вам следует использовать подмодули, поскольку простые проверки не следует изменять напрямую.
По умолчанию Carthage перестроит зависимость независимо от того, является ли она той же разрешенной версией, что и раньше. Передача --cache-builds заставит Carthage избегать перестроения зависимости, если это возможно. См. информацию о файлах версий для получения подробной информации о том, как Carthage выполняет это кэширование.
Примечание. В настоящее время --cache-builds несовместим с --use-submodules . Использование обоих приведет к тому, что рабочая копия и зафиксированные изменения в зависимости вашего подмодуля не будут правильно перестроены. Подробности см. в № 1785.
Автоматическое завершение команд и параметров Carthage доступно, как описано в Bash/Zsh/Fish Completion.
Carthage официально поддерживает только динамические фреймворки . Динамические фреймворки можно использовать в любой версии OS X, но только в iOS 8 или новее . Кроме того, начиная с версии 0.30.0 Carthage поддерживает статические платформы.
Поскольку в Carthage нет централизованного списка пакетов и формата спецификации проекта, большинство платформ должны собираться автоматически .
Конкретные требования любого рамочного проекта перечислены ниже.
Carthage будет создавать только те схемы Xcode, которые используются в вашем .xcodeproj . Вы можете убедиться, что все намеченные вами схемы собраны успешно, запустив carthage build --no-skip-current и затем проверив папку Carthage/Build.
Если важная схема не создана при запуске этой команды, откройте Xcode и убедитесь, что схема помечена как Shared , чтобы Carthage мог ее обнаружить.
Если вы столкнулись с ошибками сборки в carthage build --no-skip-current , попробуйте запустить xcodebuild -scheme SCHEME -workspace WORKSPACE build или xcodebuild -scheme SCHEME -project PROJECT build (с фактическими значениями) и посмотрите, не произойдет ли там тот же сбой. Мы надеемся, что это даст достаточно информации для решения проблемы.
Если у вас установлено несколько версий инструментов разработчика Apple (например, бета-версия Xcode), используйте xcode-select чтобы изменить версию, которую использует Carthage.
Если вы все еще не можете создать свою платформу с помощью Carthage, пожалуйста, откройте проблему, и мы будем рады помочь!
Carthage определяет, какие версии вашей платформы доступны, путем поиска по тегам, опубликованным в репозитории, и пытается интерпретировать каждое имя тега как семантическую версию. Например, в теге v1.2 семантическая версия — 1.2.0.
Теги без номера версии или с любыми символами после номера версии (например, 1.2-alpha-1 ) в настоящее время не поддерживаются и будут игнорироваться.
Carthage может автоматически использовать готовые платформы вместо создания с нуля, если они прикреплены к выпуску GitHub в репозитории вашего проекта или через двоичный файл определения проекта.
Чтобы предложить готовые платформы для определенного тега, двоичные файлы для всех поддерживаемых платформ должны быть заархивированы в один архив, и этот архив должен быть прикреплен к опубликованному выпуску, соответствующему этому тегу. Вложение должно включать в себя .framework (например, ReactiveCocoa.framework.zip ), чтобы указать Carthage, что оно содержит двоичные файлы. Структура каталогов архива имеет произвольную форму, но фреймворки должны появляться в архиве только один раз , поскольку они будут скопированы в Carthage/Build/<platform> на основе их имени (например, ReactiveCocoa.framework ).
Чтобы предложить готовые XCFrameworks, выполните сборку с помощью --use-xcframeworks и выполните тот же процесс, чтобы заархивировать все XCFrameworks в один архив. Включите .xcframework в имя вложения. Начиная с версии 0.38.0, Carthage предпочитает загружать вложения .xcframework при передаче --use-xcframeworks .
Выполнить операцию архивирования с самим Carthage можно с помощью:
-carthage build --no-skip-current
-carthage archive YourFrameworkNameили альтернативно
carthage build --archiveЧерновики релизов будут автоматически игнорироваться, даже если они соответствуют нужному тегу.
Для создания и загрузки релизов с тегами можно использовать travis-ci.
Установите travis CLI с помощью gem install travis
Настройте travis-ci для вашего репозитория (шаги 1 и 2)
Создайте файл .travis.yml в корне вашего репозитория на основе этого шаблона. Установите для FRAMEWORK_NAME правильное значение.
Замените PROJECT_PLACEHOLDER и SCHEME_PLACEHOLDER.
Если вы используете рабочую область вместо проекта, удалите строку xcode_project и раскомментируйте строку xcode_workspace.
Проект должен быть в формате: MyProject.xcodeproj.
Рабочая область должна иметь формат: MyWorkspace.xcworkspace.
Не стесняйтесь обновлять значение xcode_sdk до другого SDK. Обратите внимание, что для тестирования на iPhoneos SDK вам потребуется загрузить удостоверение подписи кода.
Для получения дополнительной информации вы можете посетить документацию travis для проектов Objective-C.
language : objective-c
osx_image : xcode7.3
xcode_project : <PROJECT_PLACEHOLDER>
# xcode_workspace: <WORKSPACE_PLACEHOLDER>
xcode_scheme : <SCHEME_PLACEHOLDER>
xcode_sdk : iphonesimulator9.3
env :
global :
- FRAMEWORK_NAME=<THIS_IS_A_PLACEHOLDER_REPLACE_ME>
before_install :
- brew update
- brew outdated carthage || brew upgrade carthage
before_script :
# bootstrap the dependencies for the project
# you can remove if you don't have dependencies
- carthage bootstrap
before_deploy :
- carthage build --no-skip-current
- carthage archive $FRAMEWORK_NAME Запустите travis setup releases , следуйте документации здесь.
Эта команда закодирует ваши учетные данные GitHub в файл .travis.yml , чтобы Трэвис мог загрузить выпуск на GitHub.com. Когда будет предложено загрузить файл, введите $FRAMEWORK_NAME.framework.zip
Обновите раздел развертывания для запуска по тегам:
В .travis.yml найдите:
on :
repo : repo/repo И добавьте tags: true skip_cleanup: true :
skip_cleanup : true
on :
repo : repo/repo
tags : trueЭто позволит Трэвису знать, что нужно создать развертывание при отправке нового тега, и не позволит Трэвису очистить сгенерированный zip-файл.
Если вы встраиваете в свое приложение множество динамических фреймворков, время его запуска перед основным запуском может быть довольно медленным. Carthage может помочь смягчить это, создавая вместо этого ваши динамические фреймворки как статические. Статические платформы можно связать непосредственно с вашим приложением или объединить в более крупную динамическую структуру с помощью нескольких простых изменений в вашем рабочем процессе, что может привести к значительному сокращению времени запуска перед основным запуском.
Начиная с версии 0.30.0 проект Carthage реализует поддержку статически связанных фреймворков, написанных на Swift или Objective-C, поддержка которых была введена в Xcode 9.4. Однако обратите внимание, что там конкретно говорится frameworks , поэтому пакеты Darwin имеют расширение .framework и статически связанные архивы объектов внутри. Carthage в настоящее время не поддерживает схемы статических библиотек , и нет никаких планов по их поддержке в будущем.
Рабочий процесс практически не отличается:
Однако:
Подробности см. в документе StaticFrameworks.
Обратите внимание, что к этому подходу применимо несколько предостережений:
Хотите рекламировать, что ваш проект можно использовать с Carthage? Вы можете добавить значок совместимости:
… в ваш README , просто вставив следующий Markdown:
[ ![ Carthage compatible ] ( https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat )] ( https://github.com/Carthage/Carthage ) Предварительно созданную платформу нельзя отладить с помощью пошагового выполнения на другом компьютере, кроме того, на котором платформа была создана. Просто carthage bootstrap/build/update --no-use-binaries должен это исправить, но более автоматизированное решение см. в #924. Dupe rdar://23551273, если вы хотите, чтобы Apple устранила основную причину этой проблемы.
Большая часть функциональности инструмента командной строки carthage фактически инкапсулирована в инфраструктуру CarthageKit.
Если вы заинтересованы в использовании Carthage как части другого инструмента или, возможно, в расширении функциональности Carthage, взгляните на исходный код CarthageKit, чтобы узнать, соответствует ли API вашим потребностям.
CocoaPods — это давний менеджер зависимостей для Cocoa. Так почему же был создан Карфаген?
Во-первых, CocoaPods (по умолчанию) автоматически создает и обновляет рабочую область Xcode для вашего приложения и всех зависимостей. Carthage собирает двоичные файлы фреймворка с помощью xcodebuild , но оставляет ответственность за их интеграцию пользователю. Подход CocoaPods проще в использовании, а подход Carthage является гибким и ненавязчивым.
Цель CocoaPods указана в README следующим образом:
… улучшить доступность сторонних библиотек с открытым исходным кодом и участие в них путем создания более централизованной экосистемы.
Напротив, Carthage был создан как децентрализованный менеджер зависимостей. Центрального списка проектов не существует, что сокращает объем работ по техническому обслуживанию и позволяет избежать каких-либо центральных точек отказа. Однако обнаружить проект сложнее — пользователям приходится обращаться к страницам трендов GitHub или аналогичным.
Проекты CocoaPods также должны иметь так называемый файл podspec, который включает метаданные о проекте и определяет, как его следует построить. Carthage использует xcodebuild для создания зависимостей, вместо того, чтобы интегрировать их в единое рабочее пространство, у него нет аналогичного файла спецификации, но ваши зависимости должны включать собственный проект Xcode, который описывает, как создавать их продукты.
В конечном итоге мы создали Carthage, потому что нам нужен был самый простой инструмент — менеджер зависимостей, который выполняет свою работу, не принимая на себя ответственность за Xcode и не создавая дополнительной работы для авторов фреймворка. CocoaPods предлагает множество удивительных функций, которых у Carthage никогда не будет, за счет дополнительной сложности.
Carthage выпускается под лицензией MIT.
Фотография фона заголовка распространяется по лицензии CC BY-NC-SA 2.0. Оригинальное фото Ричарда Мортеля.
