Carthage 教程：开始

原文：Carthage Tutorial: Getting Started
作者：Lorenzo Boaro
译者：kmyhy

更新说明：本教程由 Lorenzo Boaro 升级至 iOS 11，Xcode 9 和 Swift 4。原文作者是 James Frost。

对于 iOS 开发者来说有两个好东西，庞大的社区和海量的第三方库。

如果你在这个平台上编写过一段时间的代码，你最少也曾经和这些库中的 1 个打过交道。无论是 Alamofire、Locksmith 还是 Kignfisher，你都能了解使用他人代码的好处，因为你不想重复制造轮子。

然后 CocoaPods 出现了。如果你不知道这个贴心工具，那么我可以告诉你它是一个时髦的依赖管理器，让你顺利地将这些库继承到你的项目中。

它在 iOS 社区中的使用非常广泛，甚至 Google 都在用它们来发布它们的各种 iOS SDK。

随着 Swift 3.0 出现，苹果推出了自己的 Swift 包管理器，用于分发 Swift 3.0 以上的包。苹果将它描述为：

Swift 包管理器是一个管理 Swift 代码分发的工具。它和 Swift 编译系统集成在一起，自动处理依赖的下载、编译和链接。

虽然 CocoaPods 和 Swift 包管理器非常强大，但我们仍然有其它选择。Carthage 就是其中一个，它是一个 macOS 和 iOS 下的极其简单的依赖管理器，由一群来自 Github 的开发者编写。

它是第一个支持 Swift 的依赖管理器，实际上，Carthage 自身也是用 Swift 编写的！它完全使用动态框架来替代静态框架——这是 iOS 8 以后唯一的发布 Swift 二进制代码的方法。

在这篇教程中，你将学习到：

• 为什么以及何时使用依赖管理器，它们和 Carthage 的区别是什么
• 如何安装 Carthage
• 如何声明、安装和集成依赖到项目中
• 如何将依赖更新到其它版本
• 创建一个 app，用 DuckDuckGo API 查找属于定义

注意：本教程假定你基本熟悉 iOS 和 Swift，熟悉 Xcode 和命令行。
如果你需要复习这些内容，请查看本站的文章和视频教程。

开始

首先，下载开始项目。

它包含了 app 的基本框架，用 DuckDuckGo API 查找定义和图片。但它还有一个问题：它实际上还不能进行真正的查找。

打开 DuckDuckDefine.xcodeproj 稍微熟悉一下。留意这两个 view controller：SearchViewController 提供了一个 search bar 允许用户进行搜索，DefinitionViewController 显示找到的术语定义。

这个任务的核心是 DuckDuckGo.swift——至少当你完成以后是这样的。现在，performSearch(for:completion:) 方法空的，没有任何代码。

要能够执行搜索并显示出结果，你需要做两件事情：

• 用 DuckDuckGo API 创建查询
• 显示一张正在搜索的关键字的图片

有大量的开源库能帮助我们。Alamofire 是一个很好的 Swift 库，它简化了网络请求，AlamofireImage 能够在 Swift 和图片打交道的时候体验更佳。

你应该想到了吧？你将用 Carthage 将这两个依赖添加到项目中。

依赖管理

要将 Alamofire 和 AlamofireImage 添加到项目中，你可以访问它们的 Github 主页，下载 zip 文件或源文件，将它们拖到你的项目中。有使用 Carthage 之类的工具的必要么？

依赖管理器实现了大量方便的功能：

• 简化和标准化获取第三方代码并将它集成到项目中的过程。如果不用这样的工具，你就不得不手动拷贝源文件、拖拽已经编译好的二进制包，或者使用 Git 的 submodules 机制。
• 使第三方库在未来的升级更简单。假象一下，每当要升级库的时候，你都不得不访问依赖的 GitHub 主页，下载源文件并方到你的项目中。为什么要自己做这些事呢？
• 能够选择每个依赖的适当的、兼容的版本。例如，如果你手动添加了依赖，当它们相互依赖或者共享到其它库时就复杂了。

大部分依赖管理器都会构造一个项目依赖及其自依赖的依赖关系图表，并且判断它们的最佳版本。

你也可以手动完成同样的事情，但那值得吗？你有病吧！

Carthage vs CocoaPods

Cathage 和 CocoaPods 到底有何不同，为什么不用 CocoaPods 这个 iOS 最时髦的依赖管理器而要用 Cathage?

Carthage 的开发者觉得 CocoaPods 易用但不简单。而 Carthage 的宗旨是工具就应当超级简单。

CocoaPods 为 app 的开发和库的发布过程增加了复杂性：

• 库必须创建、更新和存储在 Podspec 文件中（或者说，如果某个库不存在的话 app 开发者必须自己来编写这个库）
• 当向项目中添加 pods 时，CocoaPods 会为每个 pod 新建一个 Xcode 项目和 target，以及一个用于包容这些 pod 的 workspace。你必须使用这个 workspace 并确信该 CocoaPods 项目能够正常运行。想象一下，这会增加多少需要维护的 build settings。
• CocoaPods 的 Podspec 是集中式存储的，如果因为某种原因它丢失了或者无法访问就会导致问题出现。

Carthage 项目的目标是提供一种比 CocoaPods 更简单的工具，更加容易理解、维护和更加的灵活。

它通过许多方式来实现这点：

• Carthage 不会修改你的 Xcode 项目或者强制你使用 workspace。
• 它不使用 Podspecs 或者不需要第三方库作者将他们的 pod 提交到集中式存储库。如果你的项目能够以 framework 形式构建，它就可以用在 Carthage 上。它能够直接使用 Git 和 Xcode 中现成的信息。
• Carthage 其实没有做太多的改变，全都是靠你自己来控制。你手动添加依赖到项目中，Carthage 会下载和编译它们。
*

注意：Carthage 为了简单起见使用的是动态框架。这意味着你的项目必须支持 iOS 8 以上。

Carthage vs Swift 包管理器

Carthage 和 Swift 包管理器有何不同？

Swift 包管理器的主要目的是以一种开发者友好的方式共用 Swift 代码。Carthage 的目标是共用动态框架。

动态框架是一个 Swift 包的超级，因为它们可以包含 Swift 代码、O-C 代码、以及非代码资源（比如图片）或者3者的结合。

注意：包是 Swift 源文件加上一个 mainfest 文件的集合。
manifest 文件定义了包的名字和它的内容。

安装 Carthage

背景知识就到此为止，接下来告诉你 Carthage 到底有多简单！

Carthage 的核心是一个用于获取和构建依赖的命令行工具。

有两个方法安装 Carthage：下载并执行 .pkg 安装包，或者用 Homebrew。和 Carthage 能够帮你安装 Cocoa 开发包一样，Homebrew 能够在 MacOS 上安装有用的 Unix 工具。

对于本教程，你将用的是 .pkg 安装包。

下载最新的 Carthage。选择 recent build，然后选择 Downloads 下面的 Carthage.pkg。

双击 Carthage.pkg 运行安装器。点击 Continue，选择安装位置，点击 Continue 然后 Install。

注意：当你运行安装器时，你会看到 “Carthage.pkg can’t be opened because it is from an unidentified developer.” 提示。此时，右键点击安装器，选择菜单中的 Open。

这样就行了！要检查 Carthage 是否安装成功，打开终端然后执行命令：

carthage version

如果一切正常，你会看到 Carthage 的版本号，表明安装成功。

注意：在写到这里的时候，Carthage 的最新版本是 0.23。

然后，你就要告诉 Carthage 你想安装的第三方库。这是用一个 Cartfile 文件的进行的。

创建你第一个 Cartfile

一个 Cartfile 是一个简单的文本文件，用于描述项目依赖，让 Carthage 知道它需要安装什么。每一行 Catfile 语句都会表明依赖的地址、依赖的名字以及选项——依赖所要使用的版本。一个 Cartfile 就好比 CocoaPods 的 Podfile 文件。

在终端中，进入项目根目录（即 .xcodeproj 相同路径）：

cd ~/Path/To/Starter/Project

用 touch 命令新建一个 Cartfile 文件：

touch Cartfile

用 Xcode 打开这个文件：

open -a Xcode Cartfile

如果你想用别的编辑器，比如 Vim，你也可以用别的编辑器。但是，请不要用 TextEdit，因为它很容易导致所谓的“智能引号”来代替简单引号，这会让 Carthage 出错。

在 Cartfile 中添加两行：

github "Alamofire/Alamofire" == 4.5
github "Alamofire/AlamofireImage" ~> 3.2

这两行告诉 Carthage 项目将依赖 Alamofire 4.5 以及 AlamofireImage，后者的版本需要兼容 3.2 的最新版本。

Cartfile 格式

Cartfile 使用了一个 OGDL (有序图数据语言) 自己。它听起来高大上，但其实很简单。每一行 Carfile 语句都由两个关键的信息组成：

• 依赖源: 告诉 Carthage 从哪里下载依赖。Carthage 支持两种源：

  • github ，用于 Github 类项目 (名副其实!)。你可以指定一个 GitHub 项目，以 用户名/项目名称的格式，就像你在上面用的一样。
  • git，一般的 Git 代码库。git 关键字后面跟上 git 库所在的路径，可以是远程 URL 比如 git://、http:// 或者 ssh://，也可以是本地地址，指向你开发机上的某个 git 库。

• 依赖版本: 告诉 Carthage 依赖的版本。有一串数字，以及根据你的意图来描述版本比较的方式：

  • == 1.0 表示 “使用精确的 1.0 版本”
  • >= 1.0 表示 “1.0 或者更高版本”

  • ~> 1.0 表示 “使用任意和 1.0 兼容的版本″,其实就是从某个版本开始，直到下一个大版本发布。

    • 如果是 ~> 1.7.5，那就是从 1.7.5 开始往上，但不概括 2.0，因为那是不兼容版本。
    • 如果是 ~> 2.0，Carthage 会使用 2.0 或更高版本，但低于 3.0 版本。
    • 兼容是基于语义版本的——更多内容请参考我们的CocoaPods Swift 使用教程。
• 分支名/tag名/提交名表示“使用指定的 git 分支/tag/提交”。例如，如果你可以指定使用 master 分支，或者 5c8a74a 这次提交。

如果你不指定版本的话，Carthage 会使用和其它依赖兼容的最新版本。你可以参考Carthage README 文件 中的具体例子。

编译依赖

写完 Cartfile，就可以使用和安装依赖了！

注意：本教程使用 Swift 4，而 Swift 4 只支持 Xcode 9。确认你的命令行工具设置使用的是 Xcode 9。在终端运行命令：

sudo xcode-select -s /Xcode-beta.app/Contents/Developer

请将 Xcode 9 beta 的路径替换成你自己的 Xcode 9 路径。

关闭 Cartfile 文件，回到终端。执行命令：

carthage update --platform iOS

这个命令告诉 Carthage 克隆 Cartfile 中指定的 git 代码库，然后将每个依赖编译成 framework。你会看到类似如下输出：

*** Fetching AlamofireImage
*** Fetching Alamofire
*** Checking out Alamofire at "4.5.0"
*** Checking out AlamofireImage at "3.2.0"
*** xcodebuild output can be found in /var/folders/cn/tknd724s0fv8pbdcbkg2sb6w0000gn/T/carthage-xcodebuild.no8ytB.log
*** Building scheme "Alamofire iOS" in Alamofire.xcworkspace
*** Building scheme "AlamofireImage iOS" in AlamofireImage.xcworkspace

–platform iOS 选项确保只编译 iOS 的 framework。如果你不指定平台，默认会编译全部平台（Mac 和 iOS）。

如果你想看一眼其它选项，你可以用 carthage help update。

默认，Carthage 会在和 Cartfile 相同目录下建一个 Carthage 目录，然后在这个目录下进行 checkout 和编译。现在打开这个目录：

open Carthage

这将打开 Finder，显示两个目录：Build 和 Checkouts。来看一下 Carthage 在里面放了些什么。

编译结果

如果你属性 CocoaPods，你会发现它对项目做了较多改变，将一个特殊的 Pods 项目放到了一个 Xcode 工作空间中。

Carthage 稍有不同。它简单地 check out 依赖的代码，编译成二进制 framework，然后将它集成到你的项目中。听起来很费事，但带来一些好处。它需要的步骤少，你能更清晰地了解对项目的所做改动。

当你执行 carthage update 时，Carthage 会生成几个文件和目录：

• Cartfile.resolved: 这个文件用于作为 Cartfile 的补充。它定义了 Carthage 真正使用和安装的依赖版本。极力推荐将这个文件提交到你的版本控制库中，因为它保证了别的开发者一开始就能够和你的依赖版本保持一致。

• Carthage 目录，包含两个子目录：

  • Build：包含了每个依赖编译好的 framework。你等会就会将它们集成到项目中。每个 framework 要么从源代码编译得来，要么从 Github 的 Releases 页中下下来。
  • Checkouts：check out 下来的依赖的源代码，这些源代码将被编译成 framework。Carthage 内部会自己维护依赖库的缓存，因此同样的源代码在不同的项目中不需要重复克隆。

是否需要将 Build 和 Checkouts 目录提交到版本控制库取决于你。这不是必须的，但这样做会导致可控你的代码库的人无论如何都会对每个依赖拥有可用的二进制和源代码。
备份它们是一种保险措施，例如当 Github 不可用或者源码库被完全删除的时候。

不要修改 Checkouts 文件夹中的代码，因为它的内容随时都会因为 carthage update 或 carthage checkou 命令而被修改，你的工作成果在眨眼间就会消失。

如果不得不修改依赖，你用 –use-submodules 选项来执行 carthage update 命令。

使用这个选项后，Carthage 会将 Checkouts 目录中的依赖以 submodule 的形式添加到 git 存储库，这样你就可以修改依赖的源代码，提交和推送到某个地方，而无需担忧被覆盖。

注意：如果其他用户想使用你的项目，而你没有提交编译好的 framework，他们必须在 check out 你的项目之后使用 carthage bootstrap 命令。
bootstrap 命令会下载和编译在 Cartfile.resolved 文件中的依赖的真实版本。
另外，carthage update 命令会用依赖的最新的兼容版本更新项目，这也许不是你想要的。

现在，这些你幸辛苦苦做好的编译成果如何使用呢？

向项目中添加 framework

回到 Xcode，在项目导航器中点击 DuckDuckDefine 项目。选择 DuckDuckDefine target，点击 General，找到 Linked Frameworks and Libraries 节。

在 Carthage 的目录 Finder 窗口中，找到 Build\iOS 目录。将 Alamofire.framework 和 AlamofireImage.framework 拖到 Xcode 的 Linked Frameworks and Libraries 节：

这会让 Xcode 将 app 和这些 framework 进行链接，你就可以在自己的代码中调用它们了。

然后，切换到 Build Phases 页，点击编辑器左上角的 + 号按钮添加一个新的 Run Script。添加一个命令：

/usr/local/bin/carthage copy-frameworks

点击 Input Files 下面的 +，为每个 framework 添加一行：

$(SRCROOT)/Carthage/Build/iOS/Alamofire.framework
$(SRCROOT)/Carthage/Build/iOS/AlamofireImage.framework

结果看起来是这个样子：

认真来讲，这个 build phase 是不需要的，项目仍然可以运行。但是，这里有一个 App 商店提交时的 Bug，app 中的 framework 中如果包含有 iOS 模拟器的二进制 image 会被 App Store 拒绝。

carthage copy-frameworkd 命令会将不用的架构去除。耶！

看起来也没什么稀奇的，Build & run 检查一切是否正常。当 app 一启动，你会看到一个 search view controller。

恩，还不错。一切正常。接下来是升级依赖。

升级 framwork

我得坦白一件事情。

还记得之前创建的 Cartfile 文件么？我说过的 Alamofire 和 AlamofireImage 安装版本是多少？呃，听着，我弄错了。我把 Alamofire 的版本弄成旧版本了。

但是别这几！这完全是好意。你可以把这个看成一个机会……是的，学习如何升级一个依赖的机会。其实这是一个惊喜。

打开你的 Cartfile。在终端中，在你的项目目录下，运行：

open -a Xcode Cartfile

将 Alamofire 这行改为：

github "Alamofire/Alamofire" ~> 4.5.0

就和之前所说的，这表示使用 4.5 的兼容版本，包括高于 4.5 的版本但不包括后面的 5.0 版本。

在用 Carthage 添加依赖时，最好考虑一下兼容性并将版本限制在你正在对标的版本。这样，你能够知道 API 和功能的真实状态。

例如，依赖的 5.0 版本可能包含 app 不兼容的 API 修改——如果你的项目是基于 4.5 构建，你很可能不需要自动升级。

保存并关闭 Cartfile，回到终端。执行升级：

carthage update --platform iOS

Carthage 会查找所有依赖的新版本，check out 它们，如果需要的话也会编译它们。你会看到它会下载最新版本的 Alamofire。

因为你的项目已经包含了一个对编译好的 Alamofire 的 .framework 文件引用，Carthage 重新编译时会将新版本编译在同一位置，因此你可以坐下来静等 Carthage 为你干活，你的项目会自动使用 Alamofire 的最新版本！

Duck,Duck… GO!

下载你已经集成了 Alamofire 和 AlamofireImage，你可以用他们来进行网络搜索了。准备好了吗？

在 Xcode 中打开 DuckDuckGo.swift，在文件头部，加入 import 语句：

import Alamofire

然后，修改 performSearch(for:completion:) 方法：

func performSearch(for term: String,completion: @escaping (Definition?) -> Void) {
  // 1
  let parameters: Parameters = ["q": term,"format": "json","pretty": 1,"no_html": 1,"skip_disambig": 1]

  // 2
  Alamofire.request("https://api.duckduckgo.com",method: .get,parameters: parameters).responseData { response in
    // 3
    if response.result.isFailure {
      completion(nil)
      return
    }

    // 4
    guard let jsonData = response.result.value else {
      completion(nil)
      return
    }

    // 5
    let decoder = JSONDecoder()
    let definition = try? decoder.decode(Definition.self,from: jsonData)

    // 6
    if let definition = definition,definition.resultType == .article {
      completion(definition)
    } else {
      completion(nil)
    }
  }
}

代码有点多，我们将它分成几步：

1. 首先，你将构建发送给 DuckDuckGo 的参数列表。其中最重要的有两个：q: 搜索关键字，format：告诉 web 端以 JSON 作为响应格式。
2. 用 Alamofire 进行请求。这里创建了一个 GET 请求，请求地址是 https://api.duckduckgo.com,请求参数是前面创建的字典。
3. 收到响应后，检查请求是否失败。如果失败，早早退出。
4. 对响应的 JSON 进行一个可空绑定，确保其有值。
5. 用 JSONDecoder 进行反序列化，获得一个 Definition 对象，它实现了 Codable。
6. DuckDuckGo API 返回各种不同的 resultType，但这里用到的是 Article，它提供了所搜术语的简单定义。你过滤了 article，将检索结果返回给 completion 块。

注意：如果你不理解 skip_disambig 参数，那么它是告诉 DuckDuckGo 不需要返回’消歧’结果。
消歧结果你可以看看维基百科的例子：你说的的 Chris Evans 是指电影演员 Chris Evans，用过电视名人 Chris Evans 还是火车劫匪 Chris Evans？
skip_disambig 表示这个 API 会返将可能行最大的结果返回。

Build & run！当 app 启动，在 search bar 中输入 Duck。如果一切正常，你会看到这个样子。

还有一个东西忘记了，那就是图片！能够阅读鸭子是什么固然没问题，但现在的人谁愿意看字呢？一图抵——是，我不会说下半句的——你知道我想说什么。

不管怎么说，谁不喜欢看鸭子的图片？猫咪已经是上一季的事情了，不是吗？

打开 DefinitionViewController.swift，在 import UIKit 下面添加：

import AlamofireImage

然后，在 viewDidLoad 方法后添加：

override func viewDidAppear(_ animated: Bool) {
  super.viewDidAppear(animated)

  if let imageURL = definition.imageURL {
    imageView.af_setImage(withURL: imageURL,completion: { _ in
      self.activityIndicatorView.stopAnimating()
    })
  }
}

af_setImage 是一个由 AlamofireImage 提供的 UIImageView 扩展。你可以用它根据 definition 的 imageURL 来抓取图片。当图片下载完，停止 indicator 的动画。

Build & run，再次执行搜索：

呱，呱！

接下来做什么？

你可以下载完整的示例项目。别忘了执行 carthage update –platform iOS 来编译依赖。

恭喜你，你学习了依赖管理和 Carthage 后面的知识，获得了一些用 Carthage 添加依赖的实际经验，并用这些依赖创建了一个能用的 app !

你还知道如何将你的依赖升级至未来的版本。

如果你想学习 Carthage 的更多内容，你的第一站应该是 Carthage 的 README，以及 Build Artifacts 文档。

Justin Spahr-Summer，这个项目的创始人之一，在 Realm.io 上给 Carthage 来了一个精彩的演讲，标题叫做“Ruthlessly Simple Dependency Management”。

最后，如果你想学习 Swift 包管理器，请阅读官方文档。对于 CocoaPods，你可以参考我们的教程“如何在 Swift 下使用 CocoaPods”。其中包含了一节关于语义化版本的内容，你知道了，Cartfile 文件中就使用到了它。

希望本教程能让你有所收获。有任何问题和评论，请在论坛中发言。