(译)Carthage 使用说明

译者注:先吐槽一下这个名字,Carthage 名字感觉好奇怪,查了一下,解释是 n.迦太基(非洲北部,今突尼斯的奴隶制城邦,腓尼基人所建,公元146年被罗马帝国所灭,见Punic Wars) 真是没搞明白怎么起这么个蹩脚的名字,你看 CocoaPods 多形象。

Carthage 旨在用最简单的方式添加 frameworks 到 Cocoa 应用

Carthage 和 CocoaPods 的不同

CocoaPods 是一个对 Cocoa 长久保持依赖的包管理器,那为什么要创建 Carthage?

首先,CocoaPods(默认情况下)自动为你的应用创建和更新 Xcode 的 workspace 和 所有依赖。 Carthage 通过 xcodebuild 工具构建 二进制 framework,但是把集成这些framework到项目的权利留给了用户。CocoaPods 的方式比较简单,而 Carthage 更加灵活且非侵入性。

CocoaPods 的目标在它的 README 这样说道:

… to improve discoverability of, and engagement in, third party open-source libraries, by creating a more centralized ecosystem.

作为对比, Carthage 创建的是一个去中心化的依赖包管理器,这里没有项目的中心化的列表,这样可以减少维护工作和避免中心节点的失败,但是项目的发现会更加困难,用户必须去 Github 的 trending 页面去检索。

CocoaPods 项目必须有个 podspec 文件,这个文件中包含了项目的元数据以及指定了如何进行项目构建。 Carthage 使用 xcodebuild 来构建依赖,而不是集成它们到单独的 workspace,它不包含一个类似的说明文件但你的依赖必须包含它们自己的 Xcode 工程文件,该文件里描述了如何构建他们的产品。

最后,创建 Carthage 是为了提供一个最简单的工具 – 一个依赖管理器,不需要 Xcode 就可以把工作做好,不需要为 framework 作者制造额外的工作。CocoaPods 提供了许多 Carthage 没有的奇妙的特性,代价就是增加了额外复杂性的开销。

安装 Carthage

安装 carthage 到系统,请下载并运行最新的 Release Carthage.pkg 文件。
另一种选择是使用 Homebrew 并安装 carthage 工具到系统并运行 brew updatebrew install carthage
如果你想运行最新的开发版本(很有可能不稳定或不兼容),只需要简单的 clone 仓库的 master 分支,并运行 make install

添加 frameworks 到应用

一旦安装了 Carthage,就可以添加 frameworks 到你的工程了。注意:Carthage 只支持 iOS8 及以后的提供的动态 frameworks。

让我们开始吧:

如果是构建 OSX app

  1. 创建一个 Cartfile ,在这个文件中列出你想使用的 frameworks
  2. 运行 carthage update ,获取依赖到 Carthage/Checkouts 文件夹,逐个构建
  3. 在工程的 target-> General 选项下,拖拽 Carthage/Build 文件夹内想要添加的 framework 到 “Embedded Binaries” 选项下。

如果是构建 iOS app

  1. 创建一个 Cartfile ,在这个文件中列出你想使用的 frameworks
  2. 运行 carthage update ,获取依赖到 Carthage/Checkouts 文件夹,逐个构建
  3. 在工程的 target-> General 选项下,拖拽 Carthage/Build 文件夹内想要添加的 framework 到 “Linked Frameworks and Libraries” 选项下。
  4. 在工程的 target-> Build Phases 选项下,点击 “+” 按钮,选择 “New Run Script Phase” ,填入如下内容:
1
/usr/local/bin/carthage copy-frameworks

并在 “Input Files” 选项里添加 framework 路径

1
2
$(SRCROOT)/Carthage/Build/iOS/LlamaKit.framework
$(SRCROOT)/Carthage/Build/iOS/ReactiveCocoa.framework

这个脚本是针对由 universal binaries 引起的 App Store submission bug 的一种变通方案。

拷贝 debug symbols 来调试和报告 crash

  1. 在工程的 target-> Build Phases 选项下,点击 “+” 按钮,选择 “New Copy Files Phase”.
  2. 点击 “Destination” 下拉菜单,选择 “Products Directory”.
  3. 针对每个使用的 framework,拖拽它们的 dSYM 文件。

当调试信息被拷贝到 built products 目录,Xcode 在断点处将符号化调用堆栈。也可以使其深入到第三方代码中去。

当归档你的应用来提交到 AppStore 或者 TestFlight,Xcode 也会拷贝这些文件到应用的 .xcarchive bundle 的 dSYMs 子目录。

同步

在这个过程中,Carthage 会创建一些 Artifacts,最重要的是 Cartfile.resolved 文件,该文件列出了每个 framework 构建的各个版本。确保提交你的Cartfile.resolved, 因为任何人都需要那个文件来构建相同的 framework 版本。

在你完成了上述步骤并 push 了你的改变,其他用户只需要 fetch 这个仓库,运行 carthage boostrap来开始你添加的 framework。

添加 frameworks 到单元测试或者某个 framework

使用 Carthage 为任意目标做依赖与 在应用中使用 Carthage 很像,主要的不同之处在于 frameworks 是如何在 Xcode 中进行设置和链接的。

因为非应用类的 targets 在构建设置中没有 “Embedded Binaries” 选项,你必须拖拽 built frameworks 到 build phase 选项中的 “Link Binaries With Libraries”

在很少情况下,可能要拷贝每个依赖到自己的构建项目(比如,在外部 framework 中嵌入依赖,或者确保依赖在 test bundle 中出现)。怎么做呢?在 Build Phases 选项下点击左上角 “+” 按钮,选择 “New Copy Files Phases”,然后在 Copy Files 选项下的 Destination 选择器中选择 Frameworks,同时添加 framework 的引用。

升级 frameworks

如果修改 Cartfile,或者将每个 framework 升级到最新的版本,只需要再次运行 carthage update

嵌套依赖

如果将要添加的 framework 依赖已经显式列在了 Cartfile 文件中,Carthage 将自动获取。然后必须亲自从 Carthage/Build 文件夹中拖拽它们到自己的项目中。

使用 submodules 做依赖

默认情况下,Carthage 将直接 checkout 依赖源文件到项目文件夹中,提交或者忽略全自己掌控。如果希望依赖用 Git submodules 代替(或许这样你就可以在他们内部commit,push),可以通过运行 carthage update 或者 carthage checkout --use-submodules

运行之后,Carthage 会在仓库中写入 .gitmodules.git/config 文件,并自动更新当依赖的版本发生变化的时候。

自动重新构建依赖

在开发过程中,如果想修改依赖项目中的代码,并在编译父项目的时候自动重新编译,可以添加一个 Run Script 来唤醒 Carthage,像这样:

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

注意:在这样做之前首先需要 使用 submodules,因为 plain checkouts 不能被直接修改

为你的 framework 支持 Carthage

Carthage 官方只支持 dynamic frameworks. Dynamic frameworks 在OSX上支持任何版本,iOS上只支持 iOS8 及以上版本。

由于 Carthage 没有中心化的 package list,没有项目说明格式,大部分 frameworks 应该自动构建

关于 framework 的特定要求如下:

分享你的 Xcode schemes

Carthage 只构建从 .xcodeproj 分享出来的 Xcode schemes。可以通过运行 carthage build --no-skip-current 来检测所有的 intended schemes 是否构建成功,然后检查 Carthage/Build 文件夹。
如果运行命令的时候,一个重要的 scheme 没有构建成功,打开 Xcode 确保 scheme is marked as “Shared” ,这样 Carthage 可以发现它。

解决构建失败

如果运行 carthage build --no-skip-current 时遇到构建失败,尝试运行 xcodebuild -scheme SCHEME -workspace WORKSPACE build 或者 xcodebuild -scheme SCHEME -project PROJECT build (用具体值) 看是否出现同样的错误。这很有可能提供足够的信息来解决问题。

如果 Apple developer tools 安装有多个版本(比如安装了Xcode beta),use xcode-select来选择 Carthage 最终使用哪个版本。

如果仍然不能用 Carthage 构建 framework,请 open an issue 我们会提供帮助。

给稳定版本打标签

Carthage 通过搜索发布到仓库中的 tag 来决定 framework 的哪个版本是可用的,并试着将每个 tag 翻译成 semantic version。比如,tag v1.2,语义版本是 1.2.0

没有数字版本号的 tag,或者 有任何字符跟在数字版本号后边(比如:1.2-alpha-1)目前是不支持的,将会被忽略。

将预构建的 frameworks 归档到一个 zip 文件

如果依附于一个 GitHub Release,Carthage 自动使用预构建 framework,而不是从头构建。
为了给预构建 framework 提供一个指定的 tag,所有支持的平台的二进制文件被压缩成一个 archive,这个 archive 依附于一个发布的响应那个 tag 的 Release。附件应该包含 .framework 在它们的名字(比如:ReactiveCocoa.framework.zip),来表明 Carthage 它包含了二进制包。

Prerelease or draft Releases 将被自动忽略,即使响应对应的tag。

声明你的兼容性

如果想声明你的项目支持 Carthage,可用添加一个兼容性的 badge 到 README文件,只需简单插入如下 Markdown:

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

CarthageKit

Carthage 大部分的功能都被打包到一个称作 CarthageKit 的 framework 中了。
如果喜欢使用 Carthage 作为另一个工具的一部分,或者扩展 Carthage 的功能,看一下 CarthageKit 源码中的 API 是否符合你的需求。

翻译自:https://github.com/Carthage/Carthage/blob/master/README.md