Swift Package Manager 教程

翻译自原文

是时候学习如何使用 Swift Package Manager 去处理外部依赖、在 macOS 和 linux 上创建你自己的 Swift 库和 app 了。

Swift Package Manager 基础

注意：由于 Apple 在 Swift 4 中为 Swift Package Manager 的 API 做了一个完全的重新设计（你可以阅读相关更改的内容），本教程并不适用于 Swift 3。 所以首先在我们开始之前，请在检查你的设备上的 Swift 版本。

swift --version
Apple Swift version 4.0.2 (swiftlang-900.0.69.2 clang-900.0.38)
Target: x86_64-apple-macosx10.9

创建 apps

所有困难的工作都可以交由 swift package 命令来完成。你可以在终端中输入该命令查看可用的子命令。为了生成一个新的包，你应该使用初始化命令。如果你不提供一个类型标志，默认情况下该命令将会生成一个库，但这一次我们想要生成一个可执行的应用。

swift package init --type executable 
swift build 
swift run my-app

编译器可以在 swift build 命令的帮助下构建你的源文件。该可执行文件将会被放置在 .build/ 目录下的某个地方，如果你使用 swift run my-app 命令来运行刚刚创建的应用，你应该呢个看到基本的 'Hello, world!' 消息。

祝贺你成功生成了你的第一个命令行 Swift 应用程序！

现在你应当来做一些切实的编码了。通常而言你的 Swift 源文件应该在 Sources 目录下， 然而你可能想要为你的 app 创建一些可复用的部分。所以让我们通过创建一个全新的库来为这个场景做准备吧。

生成一个 Library

我们依旧从从初始化命令开始，但这次我们不指定 init 的类型了。实际上我们可以键入 swift package init --type library 但这需要键入很多单词。 😜 另外由于我们正在生成一个库， SPM 将会给我们提供一些基本的测试，让我们使用 swift test 命令来运行它们吧。

swift package init
swift test

如果你此时检查文件结构，你会在 Tests 下看到一个单元测试的例子，而不会在 source 中找到 main.swift 文件。

现在你有了一些基础了。你有一个示例程序和一个 library， 让我们在 Swift Package Manager Manifest API 的帮助下将它们链接在一起吧。

The Manifest API(清单 API) - Package.swift

每一个 SPM 包内都有一个 Package.swift 清单文件(manifest file). 在清单文件中你可以定义你的全部依赖、targets 甚至为你的工程定义指定的源文件.在本节我会教你清单文件 (manifest file) 的一些基础内容.

工具版本

首先如果你想支持新的 manifest file 的格式 (换言之, Swift 4 版本) ， 你得以注释的方式在你的 manifest 文件设置 swift-tools-version.

// swift-tools-version:4.0

现在你已经准备好在全新的 manifest API 下工作了！

依赖

让我们先通过在 Package.swift 文件中创建一个新的包依赖 (package dependency) 来为主程序添加一个依赖库. 第一个参数是一条包 url 字符串，可以是本地文件路径也可以是远程 url (通常是一个 github 仓库链接). 注意, 你还应当将你的依赖添加到 targets 中. 通常而言包的特定名称 (包名) 已经在该 library 的 manifest 文件中定义了.

// swift-tools-version:4.0

import PackageDescription

let package = Package(
    name: "my-app",
    dependencies: [
        .package(url: "../my-lib", .branch("master")),
    ],
    targets: [
        .target(
            name: "my-app",
            dependencies: ["my-lib"]
        ),
    ]
)

如果你现在运行 swift build 你将编译源文件失败. 那是因为 SPM 仅会工作在 git 仓库下. 这就意味着你需要为你的 library 创建一个 git 仓库. 让我们移动到该目录并执行如下命令:

git init
git add .
git commit -m 'initial'

你也应当标记我们指定的包依赖的分支。你可以使用 version 号，甚至也可以用 commit hashes 。所有可用的选项都很好的被写在了 manifest api redesign proposal 文档中。

现在让我们回到应用目录并使用 swift package update 命令来更新以来。这次它就能够获取、克隆并成功搞定我们的依赖了。

你可以构建并运行，然而我们忘了设置我们 library 中结构体的访问级为 public， 所以从该 API 中看不到任何东西。

public struct my_lib {
    public var text = "Hello, World!"

    public init() {}
}

让我们来做一些修改并将其提交到该 library 的主分支上。

git add .
git commit -m 'access level fix'

你已经准备好在 app 中使用该 lib 了，修改 main.swift file 如下。

import my_lib

print(my_lib().text)

再一次更新依赖，这次我们来构建一个 release 构建。

swift package update
swift build -c release
swift run -c release

通过 -c 或 --configuration 标识你可以生成一个 release 构建。

Products 与 targets

默认情况下， SPM 与下列 targets 目录一起工作:

Regular targets: package root, Sources, Source, src, srcs.
Test targets: Tests, package root, Sources, Source, src, srcs.

这就表明，如果你在这些目录下创建 .swift 文件，这些源文件将根据文件路径被编译或测试。另外，生成的 mainfest 文件将仅仅包含一份构建 target (像 Xcode targets一样) , 但有时候你想要从同一个 bundle 中创建多个 apps 或 libraries. 让我们稍微修改下我们的 Package.swift, 并看看如何能创造一个全新的 target.

// swift-tools-version:4.0

import PackageDescription

let package = Package(
    name: "my-app",
    dependencies: [
        .package(url: "../my-lib", .branch("master")),
        .package(url: "https://github.com/kylef/Commander", from: "0.8.0"),
    ],
    targets: [
        .target(
            name: "my-app",
            dependencies: ["my-lib"]
        ),
        .target(
            name: "my-cmd",
            dependencies: ["Commander"],
            path: "./Sources/my-cmd",
            sources: ["main.swift"]
        ),
    ]
)

我们刚刚从 github 创建了一个新的依赖 和一个在 Sources/my-cmd 目录下只含有 main.swift 文件的全新的 target. 现在让我们创建这个目录并为这个新的 app 添加一些源码.

import Foundation
import Commander

let main = command { (name:String) in
    print("Hello, \(name.capitalized)!")
}

main.run()

使用 swift build 编译这个工程并用一个额外的 name 参数运行这个新创建的 app. 希望你能看到的输出如下:

swift run my-cmd guest
// Hello, Guest!

因此我们刚刚创建了一个全新的可执行的 target, 但如果你想将你的 targets 暴露给其他的 packages , 你应当也将它们定义为 products. 如果你打开这个 library 的 manifest 文件, 你会看到里面有个从该 library target 定义 target 字段. 通过这种方式, 包管理器可以根据给定的 product name 链接 product 依赖.

注意: 你可以定义 static 或 dynamic 的 libraries. 但推荐使用 automatic , 这样可以让 SPM 决定合适的链接.

// swift-tools-version:4.0
import PackageDescription


let package = Package(
    name: "my-lib-package",
    products: [
        .library(name: "my-lib", targets: ["my-lib"]),
        //.library(name: "my-lib", type: .static, targets: ["my-lib"]),
        //.library(name: "my-lib", type: .dynamic, targets: ["my-lib"]),
    ],
    dependencies: [
        // .package(url: /* package url */, from: "1.0.0"),
    ],
    targets: [
        .target(
            name: "my-lib",
            dependencies: []),
        .testTarget(
            name: "my-libTests",
            dependencies: ["my-lib"]),
    ]
)

部署目标(Deployment target), 其他 build flags

有时候你需要为你的包指定部署的 target. 现在 Swift Package Manager 已经能做到了 (已经有 一段时间了). 你只需要在构建阶段为编译器提供一些额外的参数就行了.

swift build -Xswiftc "-target" -Xswiftc "x86_64-apple-macosx10.12"

定义构建的 flags 也是可行的.

swift build -Xswiftc "-D" -Xswiftc "DEBUG"

现在在你的源码里面你可以检查 DEBUG 标志的存在了.

#if DEBUG
    print("debug mode")
#endif

如果你想了解更多关于构建过程的内容, 只需要键入 swift build --help 你就可以看到该构建命令可用的选项.

还有一件事

你可以通过 Swift Package Manager 来生成 Xcode Projects。

swift package generate-xcodeproj

这就是 SPM 的简单介绍了。实际上我们不仅仅介绍了 Swift Package Manager 的基础知识，也稍微拓展了一些，现在你应该对 targets、products 以及大部分可用的命令比较熟悉了，但仍然还有很多需要学习。所以如果你想对这个 amazing 的工具了解更多，这里还有一些非常棒的资源等着你去浏览。 Enjoy！ 😉

另外，本教程的源码可以在 github 上获取。

拓展阅读

• Swift.org Package Manager
• SPM usage
• SPM PackageDescription API
• SPM Manifest API redesign proposal
• SPM Manifest API redesign
• SPM Evolution