Carthage介绍(译)

Carthage v0.26.2(原文链接)

Carthage的目标是用最简单的方式来管理Cocoa第三方框架。

基本的工作流如下:

1、创建一个Cartfile,包含你希望在项目中使用的框架的列表

2、运行Carthage,将会获取列出的框架并编译它们

3、将编译完成的.framework二进制文件拖拽到你的Xcode项目当中

Carthage编译你的依赖,并提供框架的二进制文件,但你仍然保留对项目的结构和设置的完整控制。Carthage不会自动的修改你的项目文件或编译设置。

Carthage 和 CocoaPods的区别

CocoaPods是已存在很长时间的Cocoa依赖管理器,那么为什么要创建Carthage呢?

首先,CocoaPods默认会自动创建并更新你的应用程序和所有依赖的Xcode workspace。Carthage使用xcodebuild来编译框架的二进制文件,但如何集成它们将交由用户自己判断。CocoaPods的方法更易于使用,但Carthage更灵活并且是非侵入性的。

CocoaPods的目标在它的README文件描述如下:

…为提高第三方开源库的可见性和参与度,创建一个更中心化的生态系统。

Carthage创建的是去中心化的依赖管理器。它没有总项目的列表,这能够减少维护工作并且避免任何中心化带来的问题(如中央服务器宕机)。不过,这样也有一些缺点,就是项目的发现将更困难,用户将依赖于Github的趋势页面或者类似的代码库来寻找项目。

CocoaPods项目同时还必须包含一个podspec文件,里面是项目的一些元数据,以及确定项目的编译方式。Carthage使用xcodebuild来编译依赖,而不是将他们集成进一个workspace,因此无需类似的设定文件。不过依赖需要包含自己的Xcode工程文件来描述如何编译。

最后,我们创建Carthage的原因是想要一种尽可能简单的工具——一个只关心本职工作的依赖管理器,而不是取代部分Xcode的功能,或者需要 让框架作者做一些额外的工作。CocoaPods提供的一些特性很棒,但由于附加的复杂性,它们将不会被包含在Carthage当中。

安装Carthage

Carthage的安装有多种选择:

1、Installer:Carthage提供OS X平台的pkg安装文件,你可以从Github的最新release中找到,按照引导一步步安装即可。

2、Homebrew:你可以在你的OS X平台中简单的使用Homebrew命令行brew updatebrew install carthage来安装Carthage工具。(注意:如果在此之前你已经安装了二进制版本的Carthage,你应该删除它/Library/Frameworks/CarthageKit.framework

3、From source:如果你想安装最新的开发版本(可能存在稳定性和兼容性的问题),你只需要clone本仓库的master分支,然后运行make install.。需要Xcode 9.0 (Swift 4.0)

添加框架到应用程序

安装完Carthage后,你能够使用它来添加框架到你的项目。注意Carthage只支持动态框架,而后者只存在于iOS 8以上(以及任意版本的OS X)。

开始使用

如果你构建的平台是OS X

1、创建一个Cartfile,将你想要使用的框架列在里面

2、运行carthage update,将获取依赖文件到一个Carthage.checkout文件夹,然后编译每个依赖

3、在应用的targets--“General”设置下,在“Embeddel Binaries”组下,将你想使用的framework从Carthage/Build目录下拖拽进去。

另外,你需要去copy调试符号,以便在OS X上调试和生成崩溃报告。

1、在你应用target的“Build Phases”设置标签中,点击“+”号并选择“New Copy Files Phase”。

2、点击“Destination”下拉菜单并选择“Products Directory“。

3、为每个你使用的框架拖放相应的dSYM文件。

如果你构建的平台是iOS, tvOS, or watchOS

1、创建一个Cartfile,将你想要使用的框架列在里面

2、运行carthage update,将获取依赖文件到一个Carthage.checkout文件夹,然后编译每个依赖

3、在应用的targets--“General”设置下,在“Embeddel Binaries”组下,将你想使用的framework从Carthage/Build目录下拖拽进去。

4、在项目的targets--"Build Phases"设置下,点击“+”并选择"New Run Script Phase",然后创建一个运行脚本,在其中指定shell(例如/bin/sh),将以下内容添加到shell下面的脚本区域:

/usr/local/bin/carthage copy-frameworks

5、在“Input Files”下添加你想使用的framework的路径。例如:

$(SRCROOT)/Carthage/Build/iOS/Result.framework

$(SRCROOT)/Carthage/Build/iOS/ReactiveSwift.framework

$(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework

6、Add the paths to the copied frameworks to the “Output Files”, e.g.:

$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/Result.framework

$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveSwift.framework

$(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/ReactiveCocoa.framework

With output files specified alongside the input files, Xcode only needs to run the script when the input files have changed or the output files are missing. This means dirty builds will be faster when you haven't rebuilt frameworks with Carthage.

This script works around anApp Store submission bugtriggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.

With the debug information copied into the built products directory, Xcode will be able to symbolicate the stack trace whenever you stop at a breakpoint. This will also enable you to step through third-party code in the debugger.

When archiving your application for submission to the App Store or TestFlight, Xcode will also copy these files into the dSYMs subdirectory of your application’s.xcarchivebundle.

对于上述的两个平台

在整个过程当中,Carthage将创建一些build artifacts,其中最重要的是Cartfile.lock文件,里面将列出每个框架的具体版本,确保你提交了这个文件到版本控制工具里面(如Git、SVN),因为每个用到项目的人都需要它来编译相同版本的框架。

(可选地)添加build phase以警告过时的依赖项

您可以添加一个Run Script phase,当你依赖项过时的时候会自动警告您。

在项目的targets--"Build Phases"设置下,点击“+”并选择"New Run Script Phase",然后创建一个运行脚本,在其中指定shell(例如/bin/sh),将以下内容添加到shell下面的脚本区域:

/usr/local/bin/carthage outdated --xcode-warnings

Swift二进制框架下载兼容性

Carthage将确认下载的Swift(和混合的objective - c / Swift)框架是与本地使用的相同版本的Swift构建。 如果有版本不匹配,Carthage将继续从源代码构建框架。 如果框架不能从源代码构建,Carthage将失败。

因为Carthage使用xcrun swift --version的输出来确定本地Swift版本,确保使用您想要使用的Swift工具链运行Carthage命令。对于大多数情况,不需要额外的去注意整个问题。但是,举例来说,如果你使用Xcode8.x 去编译一个Swift2.3的项目,一种为carthage bootstrap指定默认swift的方法是使用以下命令:

TOOLCHAINS=com.apple.dt.toolchain.Swift_2_3 carthage bootstrap

使用Carthage去运行项目

在你完成上述步骤并将你的改变推送后,项目的其他使用者只需要获取存储库,并且运行carthage bootstrap来开始使用你添加的frameworks。

向单元测试或框架添加框架

对任何任意target的依赖性使用Carthage非常类似于前面提到的给应用添加frameworks。 主要的区别在于frameworks如何在Xcode中设置和链接。

因为单元测试target在其“General”设置选项卡中缺少“Linked Frameworks and Libraries”部分,所以必须将构建的frameworks拖动到“Link Binaries With Libraries”构建阶段。

在“Build Settings”选项卡下的测试目标中,将@ loader_path/Frameworks添加到“Runpath Search Paths”(如果尚未存在)。

在极少数情况下,你可能想将每个依赖复制到你构建的产品中(例如,在外部框架中嵌入依赖项,或确保测试包中存在依赖性)。 为此,使用“Framework”目标创建一个新的“Copy Files”构建阶段,然后在那里添加框架引用。

升级框架

如果你改动了你的Cartfile,或者你想升级到框架的最新版本(服从于你指定的需求版本),执行carthage update命令可以达到目的。

如果你只是想更新一个或者

如果您只想更新一个或特定的依赖项,在update命令后面使用空格分隔开。例如:

carthage update Box

或者

carthage update Box Result

嵌套依赖关系

如果你想添加到项目中的框架的依赖已经出现在Cartfile 中了,Carthage将会为你自动检索它们。然后,你必须从Carthage/Build 文件夹将它们自己拖动到你的项目中。

如果项目中的嵌入框架具有对其他框架的依赖性,则必须将它们链接到应用程序目标(即使应用程序目标对该框架没有依赖性,也从不使用它们)。

使用子模块的依赖关系

通常,Carthage将会直接到你项目的目录下检查 依赖的源文件,让你在选择时提交或忽略它们。如果你想有依赖项作为Git子模块(或许这样你可以提交和推送改变),你可以运行carthage update或者带有--use-submodules标志的carthage checkout。

当你运行上述命令后,Carthage将.gitmodules和.git/config文件写入你的存储库,并在依赖项的版本更改时自动更新子模块。

自动重建依赖关系

如果要在开发期间处理依赖项,并希望在构建你的父项目时自动重新构建它们,则可以添加调用Carthage的 Run Script构建阶段,如下所示:

/usr/local/bin/carthage build --platform "$PLATFORM_NAME" --project-directory "$SRCROOT"

需要注意的是,在执行此操作之前应该使用子模块 ,因为不应直接修改 简单的检出。

缓存构建

默认地,Carthage将重建一个依赖关系,无论它与以前是否是一样的解析版本。通过--cache-bulids将会使得carthage去避免重建依赖。有关如何执行此缓存的详细信息,请参阅有关版本文件的信息

注意:此时--cache-builds与--use-submodules不兼容。 使用这两者将导致工作副本和对子模块依赖关系的更改提交不能正确重建。See#1785for details

Bash/Zsh/Fish completion

Auto completion of Carthage commands and options are available as documented inBash/Zsh/Fish Completion.

使你的framework支持Carthage

Carthage 正式的只支持动态框架。动态框架在OS X的任何版本都可以使用,但IOS 只能是8或者8+。

因为Carthage没有集中的包列表,没有项目规范格式,大多数框架应该自动构建

任何框架项目的具体要求如下。

分享你的Xcode schemes

Carthage将只从你的.xcodeproj中标记为已分享的Xcode schemes来编译。如果你想检查编译是否成功,执行carthage build --no-skip-current命令,然后检查Carthage.build文件夹。

如果当执行命令但有scheme没有被编译,打开Xcode并确定对应scheme被标记为“Shared”,以便Carthage能够发现它。

解决build失败

如果你在运行 Carthage build --no-skip-current中遇到构建失败,请尝试运行xcodebuild -scheme SCHEME -workspace WORKSPACE build 或 xcodebuild -scheme SCHEME -project PROJECT build(使用实际值),并查看是否发生相同的故障。 这应该有足够的信息来解决问题。

如果您安装了多个版本的苹果开发工具(例如Xcode beta),则使用xcode-selecttor更改Carthage具体使用的版本

通过以上方法仍然解决不了问题,请open an issue,我们很乐意帮助你

标签稳定版本 (Tag stable releases)

Carthage通过搜索存储库中发布的标记来确定框架的哪些版本,并试图将每个标记名称解释为语义版本。例如,在tagv1.2中,语义版本是1.2.0。

没有任何版本号的标签或版本号后面的任何字符(例如,1.2-alpha-1)目前不被支持,将被忽略。

将预编译的框架归档到一个zip文件中

如果预先构建的框架已经附加到你的项目库github发布版本 中或者通过一个二进制项目定义文件,Carthage可以自动地使用预先构建的框架,而不是从头开始构建。

要为特定标记提供预构建框架,所有被支持的平台的二进制文件应该一起压缩到一个归档中,并且该归档应附加到与该标记相对应的已发布版本。 附件应在其名称中包括.framework(例如ReactiveCocoa.framework.zip),以向Carthage表明其包含二进制文件。

你可以像下面这样通过carthage archive命令执行归档操作:

carthage bulid --no-skip-current

carthage archive YourFrameworkName

将自动忽略版本草稿,即便它们对应于所需的标签。

使用travis-ci上传你标记的预构建框架

通过使用travis-ci去编译和上传你标记的发行版是可行的。

1、通过gem install travis命令安装travis CLI

2、为您的存储库设置 travis-ci(步骤1和2)

3、根据该模板在存储库的根目录中,创建.tarvis.yml文件,

将“FRAMEWORK_NAME”设置为正确的值

替换 PROJECT_PLACEHOLDER 和 SCHEME_PLACEHOLDER

如果使用工作区而不是项目,请删除xcode_project行,并取消注释xcode_workspace行。

项目的格式应该是:MyProject.xcodeproj

工作区间的格式应该是:MyWorkspace.xcworkspace

随时更新xcode_sdk值到另一个SDK,请注意,在iphoneos SDK上的测试将需要你上传代码签名身份。

详情见travis docs for objective-c projects

language: objective-c

osx_image: xcode7.3

xcode_project:

# xcode_workspace:

xcode_scheme:

xcode_sdk: iphonesimulator9.3

env:

global:

- FRAMEWORK_NAME=

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

4、根据文档 ,运行travis setup releases

此命令会将你的github凭据编码到.travis.yml文件中,以便让travis将发行版上传到github.com当提示您上传文件时,输入$ FRAMEWORK_NAME.framework.zip

5、更新部署部分通过带标签的运行如下命令:

在.travis.yml中查找

on:

repo: repo/repo

添加tags:true和skip_cleanup:true:

skip_cleanup: true

on:

repo: repo/repo

tags: true

这将让travis知道在推送新标签时创建部署,并阻止travis清理生成的zip文件

构建静态框架以加速应用程序的启动时间

如果在你的app中嵌入过多的frameworks,他pre-main加载可能会变得相当慢。Carthage可以构建静态框架来帮助缓解这一问题。静态框架可以直接链接到您的应用程序,或者将其合并到一个更大的动态框架中,并对您的工作流进行一些简单的修改,这样可以大幅度减少pre-main加载时间。可以查看更多相关StaticFrameworks文档

请注意,这一方法有几点需要说明:

苹果没有正式支持Swift

这是一个先进的工作流,并不是内置在Carthage,YMMV

声明你的兼容性

想告诉别人你的项目支持Carthage?只需在你的README中添加一个兼容性标记,插入以下的Markdown:

[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)

CarthageKit

大多数carthage命令行工具的功能都封装在一个名为CarthageKit的框架中。

如果你希望将Carthage作为另一个工具的一部分,或者希望扩展Carthage的功能,可以看看CarthageKit的源码,检查API是否符合你的需求。


以上译文参照完善:

指尖弹灰

Carthage:去中心化的Cocoa依赖管理器

推荐阅读更多精彩内容