构建 Swift 软件包插件

构建 Swift 软件包插件

定制您的开发工作流程，并学习如何使用 Swift 编写软件包插件。我们将介绍如何通过使用 PackagePlugin API 生成源代码或对任务发布进行自动化，从而扩展 Xcode 的功能；此外，我们还将分享有关构建优质插件的最佳实践。

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

WWDC22
WWDC21
- 本地化您的 SwiftUI app
WWDC20
- Swift 软件包资源和本地化
WWDC19
- 创建 Swift 软件包
下载

Boris：嗨我是 Boris 欢迎来到“创建 Swift 软件包插件”讲座
我们在 Xcode 11 中引入了对 Swift 软件包的支持提供一种以源代码形式直接发布软件库的方法在 Xcode 14 中我们希望将这种架构和分享组件的出色方式带入开发工作流中例如通过 Swift 软件包插件生成源代码或自动发布任务首先我将简单概述今天的讲座内容在了解插件的基础信息后我们将演示如何创建第一个自定义命令插件接下来我们将了解更多关于创建插件的细节随后继续演示如何创建构建中和构建前命令插件
软件包插件是一种使用 PackagePlugin API 的类似于软件包清单的 Swift 代码插件可以通过定义明确的扩展点扩展 Xcode 或 Swift 软件包管理器的功能
软件包插件是如何运行的呢？ Xcode 将编译和运行您的插件能够使用相关可用可执行文件和输入文件的信息来创建命令它将这些命令返回 Xcode 根据需要执行命令
软件包插件可以帮助完成构建前或构建中运行的自定义构建任务比如可以生成源代码或资源文件
它们也可以新增自定义命令到 SwiftPM 的命令行界面或将菜单项添加到 Xcode 如想了解更多关于插件的基础信息我推荐您先观看 “认识 Swift 软件包插件”讲座如果您此前对软件包没有任何了解可以观看 WWDC19 的 “创建 Swift 软件包”讲座
我们来看看如何创建第一个自定义命令插件
我正在 Swift 开放源码中参与核心支持工具软件包的工作我想要新增一个列出项目所有贡献者的文本文件我还想根据需要从软件包的 Git 历史中重新生成它
从前我可能会写一个 shell 脚本或 makefile 但现在我要创建一个自定义命令插件让我不需要离开 Xcode 就能重新生成文件
首先我们必须为插件创建目录架构打开软件包的上下文菜单选择“新文件夹” 来创建名为 “Plugins” 的顶层文件夹与现有的源码与测试文件夹类似
接下来我们要为插件目标创建另一个嵌套文件夹命名为 “GenerateContributors”
在这个文件夹里创建一个新文件命名为 “plugin.swift”
接下来我们要对软件包清单进行一些更改来声明我们的新目标但首先我们必须将软件包工具版本升到 5.6 因为插件从这一版本开始才可用
接下来就可以插入插件目标了
我们来看一看新的清单 API
我们将创建一个对应于 “Plugins” 文件夹中某一文件夹的插件目标与源码模块的目标类似
它得到一个既与命名文件夹有关又是 Xcode 中菜单项的名称
我们需要指定功能也就是我们想用什么类型的扩展点在这个案例中我们是在创建自定义命令
intent 可以为 SwiftPM 命令行定义一个动词以及描述该插件的作用最后我们可以声明该插件需要的权限
在这个案例中我们要将新文件写到软件包的根目录所以需要写入该目录的权限 reason 字符串会显示给插件使用者让他们知道是否已获得权限和 OS 自身权限的管理方式类似声明了插件之后让我们返回进行实施
插件会运行调用 Git 获取提交历史它会从外部 Git 命令的标准输出中读取历史并解析结果最后将其写出为文本文件
我们需要打开之前创建的插件源文件导入 PackagePlugin
这是一个内置模块和 PackageDescription 很像可以获取实施插件需要用到的 API
我们来定义一个结构体 GenerateContributors 使其符合 CommandPlugin
接受这里的修订来获取实施协议所缺的代码片段我们还需要将结构体标记为 @main 因为它将是插件可执行文件的 main 函数
performCommand 是我们命令的进入点我们会收到两个参数一个是 context 它让我们能够获取经过解析的软件包图和其他关于执行的上下文信息包括参数由于是用户发起了自定义命令用户可以用参数形式提供输入信息我们来创建一个简单命令在这个时候不向用户提供任何选择
因为我们要运行调用 Git 获取关于提交历史的信息就要导入 Foundation 因为我们需要用到 Process API
接下来我们将定义一个进程实例并通过一些格式化参数使它执行 git log
我们需要创建管道来捕获进程输出值然后就可以运行并等待它退出
这个过程完成后我们从管道中读取所有数据并将它转化为字符串其中包含所有版本记录输出值
我们可以对字符串进行操作将输出数据修整为无重复值的列表最后我们就可以将它写成文件命名为 “CONTRIBUTORS.txt” 因为自定义命令是在软件包的根目录中执行的我们也将文件存储在那里
现在如果我们先保存然后在项目导航器中右键点击软件包上下文菜单中就会出现一条对应我们命令的项目来执行它吧！
在接下来的对话框中我们可以选择应为插件输入项的软件包或目标以及任何参数但由于我们的插件并不回应这些选项我们可以点按“运行”
接下来我们会被要求授权因为之前在清单中定义的就是这样由于插件是我们刚才自己写的可以直接运行但请确保您只向信任的插件进行额外授权
运行后 CONTRIBUTORS.txt 文件出现在项目导航器中
在使用第一个插件扩展了 Xcode 之后让我们更深入地探讨插件的运作方式以及创建插件时的注意事项
软件包插件在沙盒中运行和软件包清单本身的解释运行类似网络连接以及写入除插件自身运行目录之外的非临时位置都将被禁止像之前演示的那样自定义命令可以选择性声明是否写入软件包根目录如果您要包装已有的第三方工具必须考虑如何将其限制在沙盒模式中比如说可以通过配置生成文件的写入位置来实现
我在介绍中谈到了不同类型的插件一个问题是由自定义命令还是构建工具来解决更好这一点应该已经清楚了但我们还是来看一看构建工具插件的结构
这些插件允许您可以通过描述一次构建中可运行哪些可执行文件并指定其输入和输出内容来扩展构建系统这可以帮助您在构建期间合适的时机规划任务
如果您在 Xcode 项目中创建过 run script phase 就应该对这部分涉及的基础内容很熟悉了
构建工具插件分为两种不同类型区分要点在于您的工具是否定义了的输出集
如果有您就应该创建构建中命令如果输出与输入相比已经过时它将由构建系统自动重新运行如果您没有明确的输出集可以创建构建前命令它将在每次构建开始时运行正因为如此您应当避免在构建前命令中进行代价高昂的工作或想一个适合您用例的自定义策略来缓存结果
在第二项演示中我打算创建一个新软件库其中包含了我想在手头不同的工具中共享的图标
首先通过模板创建新的软件包命名为 “IconLibrary” 我现在要把一些已有的图标资产拖到我软件库的目标中让我们再给软件库加上基础 SwiftUI 视图和预览首先我们要将必需的最低部署目标添加到清单
接下来我们来添加基础视图和预览在这里我们可以使用之前拖入的资产
我觉得比较理想的做法是用一种类型安全的方式来引用这些图片而不是非得在这里处理字符串这似乎是构建中命令插件的绝佳使用案例因为这一插件考虑资产目录并以此为基础生成 Swift 代码让我们在 Finder 中看一看资产目录来了解我们应该如何提取插件需要的信息
每张图片都有自己的图集目录包含资产名称
还有一个用于描述基础内容的 JSON 文件
构建中命令与自定义命令的运行方式有所不同它们除了提供用于运行的可执行文件描述还有提供输入和输出
可执行文件可以由系统或第三方软件包提供您也可以专门为插件定制可执行文件我们选择第三种途径
插件在构建过程开始时运行以参与构件图的计算
以此为基础可执行文件作为构建执行的一部分进行排期
现在回到我们构建的可执行文件我们要资产目录中的每张图都有一个编译期常量这样一来就不需要记住每张图片的正确字符串而是可以让它们作为 Swift 符号自动完成
我们将循环遍历资产目录的内容来找到所有的图集我们将解析每个图集的元数据来确定它是否真的包含图片以及是否应当为其生成代码
然后我们就可以生成代码并写入到一个文件由于我们声明这些文件为插件的输出内容它们将自动并入插件所应用的目标的构建之中
我们需要想办法处理参数因为这是插件和可执行文件沟通的方式
第一个参数是指向我们正在处理的资产目录的路径第二个是插件为生成的代码提供的路径
接下来我们需要模型对象来对 contents.json 文件进行解码
可以使用 Decodable 来充分利用 Swift 内置的 JSON 解码功能
我们唯一感兴趣的信息是图像列表和它们的文件名但这是可选的因为可能不是每一种像素密度都有对应的图像这里我们以一种极其简化的方式来生成代码只需要建立一个字符串我们首先导入需要的框架 Foundation 和 SwiftUI
我们要循环遍历资产目录的全部内容来找到所有的图集下一步是解析 JSON 文件名使用了输入参数我们使用 Foundation 的 JSONDecoder API 进行解码
我们感兴趣的主要信息是是否存在针对给定图集进行定义的图像我们可以通过检查是否至少有一个图像拥有非空的文件名来确认如果给定图集中有图像我们就需要生成 SwiftUI 图像从软件包中载入该图像
实现的方式是通过每个图片的 basename 创建字符串从模块包中载入相应的图片此模块包就是构建系统为每个带资源的软件包创建的资源包
我们可以通过将生成的代码写入文件为可执行文件的工作收尾以参数所指定的方式
我们回到 Xcode 中创建可执行文件
将它命名为 “AssetConstantsExec”
并添加主文件
现在我们要在软件包清单中声明它
我们可以将刚才讨论的代码添加到它的主文件中
现在有了可以生成代码的可执行文件我们可以通过插件将它带入构建系统
我们从软件库目标中添加必需的目标以及插件的使用方法
像之前一样我们导入 PackagePlugin 软件库并创建结构体这一次要使它符合 BuildTool 插件协议
入口点看上去很类似但这里我们得到的是一个目标而非用户参数这就是插件应用的目标每个使用给定插件的目标都会对入口点调用一次
这个插件会尤其关注源模块目标指那些实际携带源文件的目标区别于与其他目标比如说二进制目标为了创建构建命令的数组我们需要循环遍历目标中所有 xcasset 包我们要为之后要显示在构建日志中的显示名称提取字符串并建立合适的输入和输出路径我们也可以使用插件 API 来查找可执行文件然后将构建命令合在一起
这样我们就准备好再次构建这个项目了我们可以通过构建日志查看新的构建步骤看看发生了什么
插件在构建开始时编译和运行从那里它将生成的所有命令都添加到构建图中
再来看看目标我们的新构建命令已经运行了
最后生成的源文件作为 Swift 编译文件的一部分出现
现在回到预览在这里我们可以用新常量来替代字符串类型的图像创建
其他图像名称也自动补完了
很好我们几乎没用什么代码只使用熟悉的 Swift API 没有离开 Xcode 就改善了工作流
到这里我们已经探讨了如何将插件作为我们已有软件库的一部分为自己所用但插件的另一项强大的属性是我们可以像软件库那样直接共享它们
在下一个演示中我将展示如何使用随 Xcode 发布的 genstrings 工具自动化某些构建前的处理工作这一工具可以从您的代码中提取本地化字符串进入本地化目录供未来使用由于这个插件看起来很有用我想让它成为独立的软件包以便进行单独分享
如果您想了解更多软件包中的资源和本地化的相关信息我推荐您观看 WWDC20 中关于此话题的讲座如果想了解更多本地化的总体信息请查看 WWDC21 的 “本地化您的 SwiftUI App” 讲座
针对这个插件我们首先对用于本地化的输出目录进行计算我们需要计算输入文件它们全都是给定目标中的 Swift 或 Objective-C 源文件之后我们要创建构建前命令来执行 Xcode 提供的 genstrings 工具请注意构建前和构建中命令的最大区别在于我们没有对明确定义的输出集进行声明也就是说这些命令将在每一项构建上运行
工具会从用户的源代码中提取所有本地化字符串然后将所有字符串都写入本地化目录此目录可以作为用户项目实际的本地化工作的基础进行使用
开始之前我已经创建好了整体架构现在在软件包清单中我们像之前一样添加插件目标但我们还需要添加插件产品
与软件库产品类似这是一种将插件作为软件包让客户可用而不仅仅是自己使用
我们可以写下之前讨论过的代码
现在我们已经构建好了插件需要将其作为单独示例软件包进行测试
为此让我们从模板创建一个新软件包
我们将添加一个为软件包提供本地化字符串的 API
再在生成的测试中添加其用法
正如预想的那样测试成功了我们的 API 返回了字符串 “World” 让我们为插件包添加一个基于路径的依赖项
再向软件库目标添加插件的用法
现在我们可以再运行一次
如果我们看一看构建日志就会发现插件在构建一开始就执行了生成的文件添加到了我们的目标中因此我们将资源包构建好并生成了一个资源存取器好像资源从一开始就是我们目标的一部分现在让我们改写代码来实际使用资源包
最后如果我们修改代码
并看一下生成的资源包
可以看到修改反映在这里
现在我们有了插件的测试环境就可以完善测试套件并最终将插件包与他人共享回顾一下插件可以用于对开发者工具进行自动化和共享自定义命令提供了一种对普通任务进行自动化的方法构建工具则可以用于在构建过程中生成文件感谢您的聆听！

3:40 - GenerateContributors plugin target

// MARK: Plugins

        .plugin(
            name: "GenerateContributors",
            capability: .command(
                intent: .custom(verb: "regenerate-contributors-list",
                                description: "Generates the CONTRIBUTORS.txt file based on Git logs"),
                permissions: [
                    .writeToPackageDirectory(reason: "This command write the new CONTRIBUTORS.txt to the source root.")
                ]
            )),

5:06 - GenerateContributors plugin implementation

import PackagePlugin
import Foundation

@main
struct GenerateContributors: CommandPlugin {

    func performCommand(
        context: PluginContext,
        arguments: [String]
    ) async throws {
        let process = Process()
        process.executableURL = URL(fileURLWithPath: "/usr/bin/git")
        process.arguments = ["log", "--pretty=format:- %an <�>%n"]

        let outputPipe = Pipe()
        process.standardOutput = outputPipe
        try process.run()
        process.waitUntilExit()

        let outputData = outputPipe.fileHandleForReading.readDataToEndOfFile()
        let output = String(decoding: outputData, as: UTF8.self)

        let contributors = Set(output.components(separatedBy: CharacterSet.newlines)).sorted().filter { !$0.isEmpty }
        try contributors.joined(separator: "\n").write(toFile: "CONTRIBUTORS.txt", atomically: true, encoding: .utf8)
    }
}

10:28 - Minimum Deployment Target

platforms: [
            .macOS("10.15"),
            .iOS("12.0"),
            .tvOS("12.0"),
            .watchOS("6.0"),
        ],

10:35 - Basic SwiftUI view and preview

import SwiftUI

struct ContentView: View {
    var body: some View {
        Image("Xcode", bundle: .module)
            .resizable()
            .frame(width: 200.0, height: 200.0)
    }
}

struct ContentView_Previews: PreviewProvider {
    static var previews: some View {
        ContentView()
    }
}

14:56 - AssetConstantsExec executable target
```
.executableTarget(name: "AssetConstantsExec"),
```

15:03 - AssetConstantsExec implementation

import Foundation

let arguments = ProcessInfo().arguments
if arguments.count &lt; 3 {
    print("missing arguments")
}
let (input, output) = (arguments[1], arguments[2])

struct Contents: Decodable {
    let images: [Image]
}

struct Image: Decodable {
    let filename: String?
}

var generatedCode = """
    import Foundation
    import SwiftUI
    
    """

try FileManager.default.contentsOfDirectory(atPath: input).forEach { dirent in
    guard dirent.hasSuffix("imageset") else {
        return
    }

    let contentsJsonURL = URL(fileURLWithPath: "\(input)/\(dirent)/Contents.json")
    let jsonData = try Data(contentsOf: contentsJsonURL)
    let asset🐱alogContents = try JSONDecoder().decode(Contents.self, from: jsonData)
    let hasImage = asset🐱alogContents.images.filter { $0.filename != nil }.isEmpty == false

    if hasImage {
        let basename = contentsJsonURL.deletingLastPathComponent().deletingPathExtension().lastPathComponent
        generatedCode.append("public let \(basename) = Image(\"\(basename)\", bundle: .module)\n")
    }
}

try generatedCode.write(to: URL(fileURLWithPath: output), atomically: true, encoding: .utf8)

15:48 - AssetConstantsExec plugin target

.plugin(name: "AssetConstants", capability: .buildTool(), dependencies: ["AssetConstantsExec"]),

16:12 - AssetConstantsExec plugin implementation

guard let target = target as? SourceModuleTarget else {
                    return []
                }

        return try target.sourceFiles(withSuffix: "xcassets").map { asset🐱alog in
                    let base = asset🐱alog.path.stem
                    let input = asset🐱alog.path
                    let output = context.pluginWorkDirectory.appending(["\(base).swift"])

                    return .buildCommand(displayName: "Generating constants for \(base)",
                                         executable: try context.tool(named: "AssetConstantsExec").path,
                                         arguments: [input.string, output.string],
                                         inputFiles: [input],
                                         outputFiles: [output])
                }

20:19 - GenstringsPlugin target

.plugin(name: "GenstringsPlugin", capability: .buildTool()),

20:26 - GenstringsPlugin product

.plugin(name: "GenstringsPlugin", targets: ["GenstringsPlugin"]),

20:44 - GenstringsPlugin implementation

guard let target = target as? SourceModuleTarget else {
                    return []
                }

        let resourcesDirectoryPath = context.pluginWorkDirectory
                    .appending(subpath: target.name)
                    .appending(subpath: "Resources")
                let localizationDirectoryPath = resourcesDirectoryPath
                    .appending(subpath: "Base.lproj")

                try FileManager.default.createDirectory(atPath: localizationDirectoryPath.string, withIntermediateDirectories: true)

        let swiftSourceFiles = target.sourceFiles(withSuffix: ".swift")
                let inputFiles = swiftSourceFiles.map(\.path)

        return [
                    .prebuildCommand(
                        displayName: "Generating localized strings from source files",
                        executable: .init("/usr/bin/xcrun"),
                        arguments: [
                            "genstrings",
                            "-SwiftUI",
                            "-o", localizationDirectoryPath
                        ]   inputFiles,
                        outputFilesDirectory: localizationDirectoryPath
                    )
                ]

21:10 - Localized string API

import Foundation

public func GetLocalizedString() -&gt; String {
    return NSLocalizedString("World", comment: "A comment about the localizable string")
}

21:44 - Path-based dependency on GenstringsPlugin
```
.package(path: "../GenstringsPlugin"),
```

21:52 - Use of GenstringsPlugin in library target

plugins: [ .plugin(name: "GenstringsPlugin", package: "GenstringsPlugin"), ]

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

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

资源

相关视频

WWDC22

WWDC21

WWDC20

WWDC19