Swift 软件包插件简介

Swift 软件包插件简介

探索如何利用 Swift 软件包插件对 Swift 软件包和 Xcode 项目执行操作。我们将讨论这些插件的运行方式，以及您可以如何借助它们来生成源代码，并对您的开发工作流程进行自动化。

资源
- - 高清视频
  - 标清视频
相关视频

WWDC23
- 认识 Swift OpenAPI Generator
WWDC22
WWDC19
- 在 Xcode 中采用 Swift 软件包
下载

♪ 柔和乐器演奏的嘻哈音乐 ♪ ♪ 您好我的名字叫 Anders 在这个视频中我将向您展示如何开始使用 Swift 软件包插件 Swift 软件包是在 Xcode 11 中引入的它们提供了一种将库作为源代码分发的好方法 Xcode 14 将这种方法扩展到开发工作流程让您可以使用插件来执行操作例如在构建过程中生成源代码或自动完成发布任务我们先来看看软件包插件是什么以及它们是如何工作的然后更详细地讨论 Xcode 14 支持的两种软件包插件即命令插件和构建工具插件首先插件是什么软件包插件是一种可以对 Swift 软件包或 Xcode 项目执行操作的 Swift 脚本插件使用 Xcode 专门为此目的提供的 API 软件包插件以 Swift 软件包的形式实现软件包可以将插件连同库和可执行文件一起提供也可以只专注于提供插件一个软件包插件可以使用多个源文件实现而用一个 Swift 软件包可定义多个插件一个高度专业化的插件可以是提供该插件的包私有的在这种情况下它只能在这个包中使用但是如果一个通用插件被定义为软件包产品该插件即可供其他包使用这样其他包也可以使用该插件使用方式类似于一个软件包如何使用另一个软件包中的库但与库不同的是插件的依赖项不会将运行时内容引入您的 App 相反它允许您访问在您自己的机器上或在您的自动构建过程中运行的开发工具那么软件包插件能做什么呢 Xcode 14 中有两种软件包插件即命令插件和构建工具插件命令插件执行您可以随时运行的自定义操作它们可以运行源代码格式化程序或 Linter 或者执行开发工作流程中包含的其他任务这可能包括根据 Git 历史记录更新源文件中的贡献者列表或版权日期也可能包括您今天要使用任意脚本完成的其他工作如果需要命令插件可以请求权限以修改包中的文件这对于代码格式化特别有用并非所有命令插件都需要写权限一些命令可以创建报告或计算代码的相关指标而无需进行任何更改构建工具插件扩展了构建系统的依赖图在构建过程中生成源代码或资源时这些插件特别有用与每次为整个包或项目调用的命令插件不同构建工具插件应用于每个需要它们的目标我们来看看如何在 Xcode 中使用命令插件这是一个小的 iOS App 可显示各种几何形状它由一个 App 项目和一个本地软件包组成这个软件包实现了一个为此 App 提供 Core Data 类型和逻辑的库我正在考虑将该包拆分到其自己的存储库中以便其他人使用在此过程中我想创建一个贡献者文件其中列出所有为该包贡献代码的开发者我可以编写一个自定义脚本来完成此工作但我知道一个包提供了一些有用的插件来处理代码我认为这个包中有一个插件可以完全满足我的需求在访问这些插件时我的操作与我需要另一个包中的库时执行的操作相同我将在本地包的清单中添加包依赖项当我保存此清单时 Xcode 会获取远程包这个包出现在 Package Dependencies 部分我注意到 Xcode 还获取了 SwiftFormat SwiftFormat 是一种流行的代码格式化工具这是因为工具包中的一个命令插件在 SwiftFormat 上有一个依赖项现在我已经添加了这个依赖项我可以访问该包提供的任何插件命令我在要应用命令的包上使用上下文菜单现在菜单中有三个新命令一个是为了使用 SwiftFormat 重新格式化源代码另外两个提供专门的操作其中一个根据 Git 中的提交历史记录生成或更新贡献者列表另一个用于更新源文件中的版权日期此处中间的命令可执行我想要的操作当我在我的包上调用该插件命令时 Xcode 让我可以选择将哪个目标传递给插件在本例中我会在整个包上调用该命令如果该插件接受自定义参数我也可以传递这里的参数我点击 Run 因为该插件会修改文件系统 Xcode 向我发出了警告我可以看到插件作者所述的想要修改代码的原因但我也想看看该插件的实现过程我选择 Show Command Xcode 向我显示了代码
这个插件执行的操作是安全的因此我将再次调用命令这次我会选择 Run
我会告诉 Xcode 记住我对这个插件做出的选择这个特定的插件使用 Git 历史记录来生成显示贡献者姓名的文件列表但是命令插件可以做的事有很大的灵活性现在我们已经在 Xcode 中使用了一个命令插件让我们仔细看看插件在后台是如何工作的软件包插件是根据需要编译和运行的 Swift 脚本每个插件都作为一个单独的进程运行插件可以访问输入包的提炼表示包括其源文件插件还获取有关包的任何依赖项的信息作为其工作的一部分许多插件会调用命令行工具插件还可以创建文件和目录并使用 Foundation 等标准库执行其他操作插件在阻止网络访问的沙盒中运行只能写入文件系统中的几个位置例如构建输出目录但是命令插件可以请求权限以修改包源目录中的文件如果用户批准沙箱将被配置为允许写入这些位置插件也可以将结果发送回 Xcode 并发出警告和错误提示构建工具插件还可以定义工具调用让 Xcode 在构建期间运行所有软件包插件都使用 Xcode 提供的 PackagePlugin 模块中的 API 这个 API 允许插件访问输入包并在适当时将结果返回 Xcode 实现插件的主源文件还定义了主入口点这个类或结构体应符合与插件类型匹配的协议 Xcode 调用的具体入口点函数取决于它是什么类型的插件您可以在 “构建 Swift 软件包插件” 视频中了解有关 PackagePlugin API 的更多信息之前我们使用一个命令插件对我们的包进行了修改让我们看一下命令插件的更多细节命令插件扩展了开发工作流程它们直接应用于包而不是在构建期间运行并非所有命令插件都会修改文件系统有些有用的操作不涉及更改任何文件但是如果一个命令确实想写入文件系统它必须在实现插件的包的清单中对此进行声明这会导致 Xcode 在让插件运行之前请求用户提供权限插件通常很小往往依赖其他工具来完成实际工作之前我们看到一个插件使用 SwiftFormat 完成所有实际工作工具包的依赖项可以是二进制文件或源代码 Xcode 将在调用命令之前从源代码构建任何所需的工具请注意插件可以由与其依赖的工具不同的包提供在命令插件的实现中主类型符合 CommandPlugin 协议插件实现 performCommand 入口点这个入口点采用上下文和用户提供的任何自定义参数让我们看一下另一种调用命令插件的方式我将使用与之前相同的项目因为我之前在 SourceCodeUtilities 包上添加了依赖项所以我可以在终端中调用相同的插件首先我要将目录改为 CoreLibs 包因为这是我要应用命令插件的包 Swift Package Manager 5.6 有一个新的插件子命令我将输入 “swift package plugin --list” 以查看可用的插件这显示了与 Xcode 菜单中相同的插件在此处的命令行中每个命令还显示了应该用来运行此命令的动词我将使用动词来重新生成贡献者列表就像我在 Xcode 中所做的那样这个插件需要写入文件系统的权限因为它将创建一个文件我输入 “yes” 以允许此操作这样该插件就可以运行并更新贡献者列表我还可以使用包管理器选项这个选项允许插件无需询问即可写入文件系统如果您从 CI 系统或其他构建自动化中调用该插件这将特别有用但在使用这个选项之前请务必了解该插件的功能就像在 Xcode 中一样我可以将命令行参数传递给该插件插件动作动词之后的任何参数都将传递给该插件在本例中我传递了一个 verbose 标志以查看该插件运行时的更多输出每个命令插件都定义了其支持的参数到目前为止我们主要讨论的是命令插件但是关于构建工具插件我还有几点要说明与命令插件不同构建工具插件不会立即完成工作反之它创建并返回构建工具调用以便 Xcode 稍后在构建包时运行每个这种工具调用都有一个要运行的命令行还有告诉 Xcode 何时运行命令行的输入和输出构建工具插件可以定义在构建期间或构建之前运行的命令我们将在一分钟内看看差异
构建工具插件返回的命令通常配置为将其输出写入构建目录因此它们在增量构建之间持续存在与插件本身一样构建工具插件定义的命令在阻止网络访问的沙盒中运行不能对包做任何更改在构建工具插件的实现中主类型符合 BuildToolPlugin 协议插件实现 createBuildCommands 入口点这个入口点需要上下文和目标来创建构建命令它返回应该在构建包时运行的任何自定义构建命令构建工具插件可以返回两种基本的构建命令普通构建命令指定输入和输出路径仅在输出不存在或输入更改时运行预构建命令在构建开始之前运行可以在事先不知道输出名称时使用预构建命令在每次构建之前运行因此它们应确保在没有更改时尽可能少地执行操作构建命令和预构建命令非常适合生成源代码或资源那么 Xcode 如何知道将哪些构建工具插件应用于包目标呢在 SwiftPM 5.6 及更高版本中包清单中有一个新的插件参数其中列出了目标所需的构建工具插件此参数指定了目标所需的任何构建工具插件就像它所依赖的任何运行时库一样这些插件可以在同一个包中也可以在不同的包中让我们回到 Xcode 我要配置我的几何 App 以使用构建工具插件在这个特定的案例中我有一个自定义命令行工具此工具可根据我的 Core Library 目标中的一些数据文件生成 Swift 代码具体细节不重要但我最后想谈谈如何为每条数据生成安全类型的 Swift 访问器除了数据文件我一直在使用一个自定义工具来生成源代码我已将这些源代码签入代码库中我一直在手动运行这个工具以重新生成 Swift 包装器代码并在我的数据文件更改时提交更改但是有了构建工具插件我可以做得更好我可以在构建期间生成代码而不必将生成的代码保存在代码库中
为了访问插件我转到包清单并在提供我要使用的源生成器插件的包上添加依赖项
我的包中的目标现在可以访问该包中定义的任何构建工具插件
现在我转到需要使用插件的目标并在其定义中添加一个插件参数
这告诉 Xcode 它想将该包中的特定构建工具应用到我的目标现在我可以从我的代码库中删除生成的源文件我们将在构建期间根据需要创建或更新这些文件
这么做整洁多了现在当我构建和运行 App 时我的构建工具插件会告诉 Xcode 在我的数据文件发生更改时调用代码生成工具生成的代码将与我的构建文件夹中的其他构建文件一起存储以保持代码库清洁在本视频中我们讨论了 Swift 软件包插件是什么以及它们是如何工作的我们还讨论了命令插件和构建工具插件之间的一些相似之处和区别这两种类型的插件让您可以将各种随机脚本替换为软件包中的一种更加结构化的可扩展性构建工具插件允许您扩展构建系统以生成源代码和资源或在构建过程中完成其他自定义工作命令插件允许您通过自定义操作自动完成常见的开发任务它们可以针对特定的工作流程进行定制也可以进行编写以用于各种不同的情况要了解如何创建您自己的软件包插件请务必观看 “创建 Swift 包插件”视频感谢观看本视频希望您喜欢 WWDC 2022 的其余部分 ♪

6:59 - General structure of a package plugin with conditional support for Xcode projects when running in Xcode

import PackagePlugin

@main
struct MyPlugin: ... {

    // Entry points specific to plugin capability. These entry points are invoked
    // when the plugin is applied to a package.

}

#if canImport(XcodeProjectPlugin)
import XcodeProjectPlugin

extension MyPlugin: ... {

    // Entry points specific to plugin capability. These entry points are invoked
    // when the plugin is applied to an Xcdeo project.

}
#endif

8:33 - Structure of a command plugin with conditional support for Xcode projects when running in Xcode

import PackagePlugin

@main
struct MyPlugin: CommandPlugin {

    /// This entry point is called when operating on a Swift package.
    func performCommand(context: PluginContext, arguments: [String]) throws {
        debugPrint(context)
    }
}

#if canImport(XcodeProjectPlugin)
import XcodeProjectPlugin

extension MyPlugin: XcodeCommandPlugin {

    /// This entry point is called when operating on an Xcode project.
    func performCommand(context: XcodePluginContext, arguments: [String]) throws {
        debugPrint(context)
    }
}
#endif

11:13 - Structure of a build tool plugin with conditional support for Xcode projects when running in Xcode

import PackagePlugin

@main
struct MyPlugin: BuildToolPlugin {

    /// This entry point is called when operating on a Swift package.
    func createBuildCommands(context: PluginContext, target: Target) throws -> [Command]
        debugPrint(context)
        return []
    }
}

#if canImport(XcodeProjectPlugin)
import XcodeProjectPlugin

extension MyPlugin: XcodeBuildToolPlugin {

    /// This entry point is called when operating on an Xcode project.
    func createBuildCommands(context: XcodePluginContext, target: XcodeTarget) throws -> [Command]
        debugPrint(context)
        return []
    }
}
#endif

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。

提交你查询的内容时出现错误。请检查互联网连接，然后再试一次。

资源

相关视频

WWDC23

WWDC22

WWDC19