SPM 使用教程：快速掌握 Swift 包管理 – wiki词典

作者： /

Here’s an article detailing the usage of Swift Package Manager (SPM):

SPM 使用教程：快速掌握 Swift 包管理

Swift Package Manager (SPM) 是 Apple 官方推出的 Swift 包管理工具，旨在简化 Swift 项目中代码的共享和复用。它与 Xcode 和 Swift 构建系统无缝集成，为管理外部库和框架提供了一个标准化、现代化的解决方案。

为什么选择 Swift Package Manager？

与 CocoaPods 或 Carthage 等第三方依赖管理工具相比，SPM 具有以下显著优势：

  • 原生集成： SPM 直接内置于 Swift 和 Xcode 中，无需额外安装或维护配置文件（如 Podfile），提供流畅的开发体验。
  • 模块化与代码复用： SPM 鼓励将代码拆分成可复用的模块，促进更清晰的项目结构和更便捷的维护。
  • 跨平台支持： SPM 不仅支持所有 Apple 平台（iOS、macOS、watchOS、tvOS），还支持 Linux，使其适用于各种 Swift 项目，包括服务器端 Swift。
  • 自动化依赖解析： 它能根据 Package.swift 文件中的规范，自动获取、构建并将外部代码链接到您的项目中。

SPM 的主要特性

  • 无缝 Xcode 集成： 在 Xcode IDE 中轻松添加和管理包。
  • 声明式包配置： Package.swift 清单文件使用 Swift 语言编写，用于定义依赖、目标和支持的平台。
  • 版本控制与依赖解析： SPM 支持语义化版本控制，以管理包更新并确保兼容性。
  • 自动化测试支持： 内置对包的构建和测试功能。

创建 Swift 包

您可以通过 Xcode 或命令行来创建一个 Swift 包。

使用 Xcode 创建

  1. 打开 Xcode。
  2. 选择 File > New > Package... (对于 Xcode 15 之前的版本，可能是 File > New > Swift Package)。
  3. 选择一个模板（例如，Library 用于可复用代码模块）。
  4. 指定包的名称和存储位置。
  5. 点击 Create。Xcode 将生成基本的包结构，包括 Package.swift 文件。

使用命令行创建

  1. 打开终端。
  2. 导航到您希望创建包的目录。
  3. 运行命令：swift package init --type [library|executable]
    • --type library：创建一个生成可复用库的包。
    • --type executable：创建一个生成可执行命令行工具的包。

此命令会生成一个基本的目录结构：

  • Package.swift：定义包配置的清单文件。
  • Sources/YourPackageName/：包含包的源代码。
  • Tests/YourPackageNameTests/：包含包的单元测试。
  • README.md：一个基本的 README 文件。
  • .gitignore：Git 忽略文件。

理解 Package.swift 文件

Package.swift 文件是定义您包的关键，它使用 Swift 语言编写，并指定以下内容：

  • products：您的包产生的构建产物（例如，库、可执行文件），这些产物对其他包可见。
  • dependencies：您的包所依赖的其他 Swift 包。
  • targets：包的基本构建块，定义模块或测试套件。目标可以依赖于同一包内的其他目标或外部依赖的产物。
  • platforms：您的包支持的操作系统和最低版本（例如，iOS、macOS）。

Package.swift 示例结构：

“`swift
// swift-tools-version:5.9
import PackageDescription

let package = Package(
name: “MyAwesomePackage”,
platforms: [
.iOS(.v13),
.macOS(.v10_15)
],
products: [
.library(
name: “MyAwesomePackage”,
targets: [“MyAwesomePackage”]),
],
dependencies: [
.package(url: “https://github.com/Alamofire/Alamofire.git”, .upToNextMajor(from: “5.8.0”))
],
targets: [
.target(
name: “MyAwesomePackage”,
dependencies: []),
.testTarget(
name: “MyAwesomePackageTests”,
dependencies: [“MyAwesomePackage”]),
]
)
“`

向项目（应用或包）添加依赖

向 Xcode 项目添加第三方包

  1. 打开您的 Xcode 项目。
  2. 选择 File > Swift Packages > Add Package Dependency...。
  3. 在搜索栏中，粘贴 Swift 包的 Git 仓库 URL（例如，https://github.com/Alamofire/Alamofire.git）。
  4. Xcode 将获取包信息。您可以选择版本规则：
    • Up to Next Major Version (推荐)： 例如，从 5.8.0 到 6.0.0。
    • Up to Next Minor Version： 例如，从 5.8.0 到 5.9.0。
    • Exact Version： 例如，5.8.0。
    • Branch： 例如，main。
    • Commit： 一个特定的提交哈希值。
  5. 点击 Next，然后选择项目中将使用此包的目标。
  6. 点击 Finish。Xcode 将下载并集成该包。

向另一个 Swift 包添加依赖（通过 Package.swift）

如果您正在开发一个 Swift 包，并希望它依赖于另一个包，您需要在 Package.swift 文件中声明它。

  1. 打开您的 Package.swift 文件。

  2. 将依赖项添加到 dependencies 数组中，指定其 URL 和版本要求。

    swift
    dependencies: [
    .package(url: "https://github.com/onevcat/Kingfisher.git", .upToNextMajor(from: "7.0.0"))
    ],

  3. 然后，在 targets 部分中，指定包内的哪个目标将使用此依赖项。

    swift
    targets: [
    .target(
    name: "MyAwesomePackage",
    dependencies: ["Kingfisher"]), // 在此处添加 "Kingfisher"
    // ...
    ]

使用依赖项

一旦添加了包，您可以使用 import 语句将其模块导入到您的 Swift 文件中。

swift
import Kingfisher

使用本地包

本地包是位于您的主项目目录中或本地文件系统上的 Swift 包，允许您在开发主应用的同时迭代开发它们。

本地包的优势

  • 模块化： 有助于将应用代码组织成独立的、可复用的组件。
  • 更快迭代： 当同时开发一个包和一个应用时，对本地包的更改会立即反映在应用中，无需推送到远程仓库。
  • 减少合并冲突： 本地包不使用 .pbxproj 文件，这可以在大型团队中减少合并冲突。
  • 改进编译时间： 如果组织得当，本地包有时可以通过只重新构建更改的模块来缩短编译时间。

在 Xcode 项目中创建本地包

  1. 打开您的 Xcode 项目。
  2. 选择 File > New > Package...。
  3. 选择 Library 模板（或其他合适的模板）。
  4. 选择您的主项目作为 Add to 目标，并选择一个分组。
  5. 关键是，如果您的应用已经处于版本控制之下，请勿创建新的 Git 仓库。
  6. 点击 Create。Xcode 将把新包作为子项目添加到您的主项目中。
  7. 将相关代码从您的主项目移动到新包的 Sources 文件夹中。
  8. 将本地包的产物添加为您的应用目标的依赖项：
    • 在项目导航器中选择您的项目。
    • 选择您的应用目标并转到 General 面板。
    • 在 Frameworks, Libraries, and Embedded Content 部分中，点击 + 按钮。
    • 选择本地包的库产物并添加它。

添加现有本地包

如果您本地机器上有一个独立的 Swift 包，并希望在 Xcode 项目中使用它：

  1. 选择 File > Swift Packages > Add Package Dependency...。
  2. 点击 Add Local 按钮（如果可用），或者直接将包含 Package.swift 文件的文件夹拖到 Xcode 项目的项目导航器中。
  3. 按照提示将包添加到您所需的目标。

常见的 SPM 命令行工具 (CLI) 命令

尽管 Xcode 提供了出色的集成，但 swift CLI 工具也提供了强大的命令，用于在 Xcode 之外管理包。

  • swift build：编译当前包及其依赖项的源代码。
    • swift build -c release：构建包的发布版本。
  • swift run [可执行目标名称]：从您的包中构建并运行可执行产物。
  • swift test：构建并运行包的测试。
  • swift package init --type [library|executable]：初始化一个新的 Swift 包。
  • swift package resolve：解析包的依赖项。
  • swift package update：获取所有依赖项的最新版本并更新 Package.resolved 文件。
  • swift package clean：清除构建产物。
  • swift package show-dependencies：显示解析后的依赖图。
  • swift package generate-xcodeproj：为您的包生成一个 Xcode 项目（适用于命令行包或不使用 Xcode 原生 SPM 集成的情况）。

Swift Package Manager 的最佳实践

遵循最佳实践可以确保您的 Swift 包易于维护、健壮且可共享。

  • 使用 Package.swift 作为清单文件： 在 Package.swift 中定义所有项目配置、依赖项和目标，并保持其组织结构清晰。
  • 版本控制 Package.swift 和 Package.resolved： 始终将这两个文件纳入您的版本控制系统。Package.resolved 锁定依赖项的确切版本，确保在不同环境中构建的一致性。
  • 语义化版本控制： 遵循 MAJOR.MINOR.PATCH 版本约定。
    • MAJOR： 对于不兼容的 API 更改。
    • MINOR： 以向后兼容的方式添加功能。
    • PATCH： 向后兼容的错误修复。
  • 使用 Git 进行依赖解析： 使用 Git URL 指定依赖项，以确保可复现性和精确的版本控制。
  • 指定 Swift 语言版本： 在 Package.swift 中明确声明 Swift 语言版本（例如，// swift-tools-version:5.9），以确保兼容性。
  • 逻辑分组目标： 在 Package.swift 中组织您的目标，以反映清晰易懂的项目结构。
  • 定期更新依赖项： 定期更新您的依赖项，以受益于错误修复、性能改进和新功能。
  • 避免混合包管理器： 在单个项目中坚持使用一个依赖管理器（SPM），以防止冲突和复杂性。
  • 清晰且描述性的包名称： 选择准确反映包用途的名称，并避免特殊字符。
  • 组织代码： 遵循将源代码放在 Sources/ 中，测试放在 Tests/ 中的约定。
  • 编写清晰的文档： 提供全面的 README 文件、行内注释和示例，以帮助他人有效使用您的包。
  • 编写彻底的单元测试： 确保您的包经过充分测试，以保持质量并防止回归。

结论

Swift Package Manager 是现代 Swift 开发中不可或缺的工具。它为管理项目依赖提供了一个原生、高效且强大的解决方案。通过掌握 SPM，您可以更轻松地构建模块化、可维护的 Swift 应用和库，并充分利用 Swift 生态系统的强大功能。

滚动至顶部