前言
Pkl（全称为 Pickle）是苹果推出的一种全新的专用于配置的编程语言。它允许开发人员通过类型和内置验证安全、直观地设计数据模型。
作为苹果语言，Pkl 有一个可用于从 .pkl 配置文件生成 Swift 接口的套件工具，这是它与其他语言的开发者有所不同的地方。
在本文中，你将学习如何安装和使用 pkl-gen-swift 命令行工具，并将其集成到你的 Swift Package Manager（SPM）项目中，方法是使用 SPM 插件。
注意：需要注意的一点是，目前 Pkl 仅适用于 macOS。
示例展示 Pkl 配置
让我们首先创建一个名为 Config 的简单 Pkl 模块，其中包含一组属性，用于定义一个小型 macOS Swift Package 库的配置，Config.pkl 文件配置如下：
module Config
baseUrl: String
retryCount: Int(isBetween(0, 3))
timeout: Duration如上面的片段所示，我们使用类型和范围来约束可以分配给属性的值，并减少错误的可能性。
Pkl CLI 工具将使用这些类型来验证配置文件并帮助生成 Swift 接口。
现在让我们编写一个单独的 .pkl 文件，修改我们之前创建的模块文件，并为本地开发提供配置值，local.pkl 配置如下：
amends "Config.pkl"
baseUrl = "https://localhost:8080"
retryCount = 0
timeout = 30.s就像这样，我们编写了一个小型配置，并指定了一些类型和约束，我们可以强制执行它们。
现在让我们安装pkl命令行工具，并评估定义实际值的模块，终端执行命令如下：
# Install pkl
curl -L -o pkl https://github.com/apple/pkl/releases/download/0.25.2/pkl-macos-aarch64
chmod +x pkl
# Evaluate the local file
./pkl eval Sources/ClientExample/Resources/local.pkl上述命令的输出将打印正确的值，这意味着配置可以正确验证：
baseUrl = "https://localhost:8080"
retryCount = 0
timeout = 30.s生成 Swift 绑定
正如我在文章开头提到的，使用Pkl定义配置的最强大功能之一是，你可以为你的应用程序生成 Swift 接口。
要从 .pkl 文件生成 Swift 接口，你需要安装 pkl 和 pkl-gen-swift 命令行工具。
手动安装和使用 pkl-gen-swift
首先，让我们安装 pkl-gen-swift 命令行工具：
curl -L https://github.com/apple/pkl-swift/releases/download/0.2.3/pkl-gen-swift-macos.bin -o pkl-gen-swift
chmod +x pkl-gen-swift现在，让我们通过在终端中运行以下命令来从 .pkl 文件生成 Swift 接口：
PKL_EXEC=./pkl
./pkl-gen-swift Sources/ClientExample/Resources/*.pkl -o Sources/ClientExample/Generated请注意，pkl-gen-swift 依赖于 pkl 命令行工具，后者需要在你的 PATH 中可用，或者可以使用 PKL_EXEC 环境变量指定。
命令的输出将是一个包含生成接口的单个 Swift 文件：
路径 Sources/ClientExample/Generated/Config.pkl.swift 下文件源代码如下：
// Code generated from Pkl module `Config`. DO NOT EDIT.
import PklSwift
public enum Config {}
extension Config {
public struct Module: PklRegisteredType, Decodable, Hashable {
public static var registeredIdentifier: String = "Config"
public var baseUrl: String
public var retryCount: Int
public var timeout: Duration
public init(baseUrl: String, retryCount: Int, timeout: Duration) {
self.baseUrl = baseUrl
self.retryCount = retryCount
self.timeout = timeout
}
}
/// Load the Pkl module at the given source and evaluate it into `Config.Module`.
///
/// - Parameter source: The source of the Pkl module.
public static func loadFrom(source: ModuleSource) async throws -> Config.Module {
try await PklSwift.withEvaluator { evaluator in
try await loadFrom(evaluator: evaluator, source: source)
}
}
/// Load the Pkl module at the given source and evaluate it with the given evaluator into
/// `Config.Module`.
///
/// - Parameter evaluator: The evaluator to use for evaluation.
/// - Parameter source: The module to evaluate.
public static func loadFrom(
evaluator: PklSwift.Evaluator,
source: PklSwift.ModuleSource
) async throws -> Config.Module {
try await evaluator.evaluateModule(source: source, as: Module.self)
}
}创建 SPM 命令插件
假设你不希望所有积极参与你的 Swift Package 的人在修改配置时手动安装所有必需的工具以生成代码。
相反，你可以创建一个 Swift Package Manager 命令插件，该插件将封装两个命令行工具，并公开一个客户友好的命令，该命令将查找所有配置文件并从中生成 Swift 接口。
让我们考虑以下 Swift Package，代码如下：
// swift-tools-version: 5.9
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "PklSwiftPlugin",
platforms: [
// 1
.macOS(.v13),
],
products: [
// 2
.plugin(name: "PklSwiftCommand", targets: ["PklSwiftCommand"])
],
dependencies: [
// 3
.package(url: "https://github.com/apple/pkl-swift.git", exact: "0.2.3")
],
targets: [
// 4
.plugin(name: "PklSwiftCommand",
capability: .command(intent: .custom(verb: "swift-pkl", description: ""),
permissions: [.writeToPackageDirectory(reason: "Write pkl to pkg")]),
dependencies: [.product(name: "pkl-gen-swift", package: "pkl-swift"), "Pkl"]),
// 5
.binaryTarget(name: "Pkl",
path: "Pkl.artifactbundle"),
// 6
.target(name: "ClientExample",
dependencies: [.product(name: "PklSwift", package: "pkl-swift")])
]
)让我们一步一步来解释上面的内容：
- 我们声明该包仅适用于 macOS 13 及更高版本，以满足
pkl-swift的要求。 - 我们声明了一个新产品，类型为插件，将用于公开
swift-pkl命令。 - 我们将 Apple 的 pkl-swift 声明为包的唯一依赖项。pkl-swift 提供了 Pkl 语言的 Swift 绑定和用于生成 Swift 接口的可执行文件。
- 我们为
swift-pkl命令插件声明了一个新目标。我们还声明了插件的依赖项，其中包括pkl-gen-swift可执行文件和Pkl命令行工具的构件束。幸运的是，我们可以依赖于pkl-swift包中的可执行文件产品来将 Swift 生成器作为依赖项，但我们需要手动创建一个pkl命令行工具的构件束。 - 我们为
pkl命令行工具的构件束声明了一个新的二进制目标。 - 我们为用于测试的库声明了一个新目标。这是包含
.pkl配置文件的目标。
要创建一个封装 pkl 命令行工具的构件束，你只需要创建一个与包清单中声明的相同名称的目录，后面跟上 .artifactbundle 扩展名。在此目录中，创建以下文件夹结构：
Pkl.artifactbundle
├── info.json
├── pkl-0.25.2-macos
│ └── bin
│ └── pklinfo.json 文件应包含以下内容：
{
"schemaVersion": "1.0",
"artifacts": {
"pkl": {
"version": "0.2.3",
"type": "executable",
"variants": [
{
"path": "pkl-0.25.2-macos/bin/pkl",
"supportedTriples": ["arm64-apple-macosx"]
}
]
}
}
}现在让我们编写命令插件的代码，该代码将从上下文中检索命令行工具，迭代目标以查找所有 .pkl 文件，然后最终运行 pkl-gen-swift 可执行文件以生成 Swift 接口，路径 Sources/PklSwiftCommand/main.swift 下的源代码如下：
import PackagePlugin
import Foundation
@main
struct PklSwiftCommandPlugin: CommandPlugin {
func performCommand(context: PluginContext, arguments: [String]) async throws {
let pklGenSwift = try context.tool(named: "pkl-gen-swift")
let pkl = try context.tool(named: "pkl")
let pklGenSwiftURL = URL(filePath: pklGenSwift.path.string)
for target in context.package.targets {
let dirEnum = FileManager.default.enumerator(atPath: target.directory.string)
var pklFiles = [Path]()
while let file = dirEnum?.nextObject() as? String {
if file.hasSuffix(".pkl") {
pklFiles.append(target.directory.appending(subpath: file))
}
}
let process = Process()
process.executableURL = pklGenSwiftURL
process.arguments = pklFiles.map { $0.string } + ["-o", target.directory.appending(subpath: "Generated").string]
process.environment = ["PKL_EXEC": pkl.path.string]
try process.run()
process.waitUntilExit()
let gracefulExit = process.terminationReason == .exit && process.terminationStatus == 0
if !gracefulExit {
throw "🛑 The plugin execution failed with reason: \(process.terminationReason.rawValue) and status: \(process.terminationStatus) "
}
}
}
}
extension String: Error {}现在可以像这样运行命令插件：
swift package --disable-sandbox swift-pkl --allow-writing-to-package-directory请注意，你需要使用 --disable-sandbox 标志，否则插件将无限期挂起。命令的输出结果与以前相同。
加载 Pkl 配置
现在我们已经生成了 Swift 接口，可以使用以下代码将其加载到我们的应用程序中，路径 Sources/ClientExample/main.swift 下源代码如下：
import PklSwift
import Foundation
func load() async throws {
let pklGenSwift = Bundle.module.bundleURL.deletingLastPathComponent().appending(path: "pkl-gen-swift").path
let pklFile = Bundle.module.url(forResource: "local", withExtension: "pkl")!
setenv("PKL_EXEC", pklGenSwift, 1)
let config = try await SomeConfig.loadFrom(source: .path(pklFile.path))
print(config.baseUrl)
print(config.timeout)
print(config.retryCount)
}在尝试执行与文档中相同的代码时，我遇到了一个问题，即 PklSwift 无法在路径中找到 pkl。因此，我必须手动设置 PKL_EXEC 环境变量在示例可执行文件中。
总结
本文介绍了 Pkl，这是苹果推出的一种专用于配置的新编程语言。它允许开发人员通过类型和内置验证安全地设计数据模型。Pkl 具有一套工具，可用于从 .pkl 配置文件生成 Swift 接口，这是其与其他语言的区别之一。文章详细介绍了如何安装和使用 pkl-gen-swift 命令行工具，并将其集成到 Swift Package Manager（SPM） 项目中。然后，通过示例展示了如何创建和修改 Pkl 配置文件，以及如何使用 pkl 命令行工具评估配置文件。接着，介绍了如何生成 Swift 接口文件，以及如何创建 SPM 命令插件来自动生成代码。
ios
**粗体** _斜体_ [链接](http://example.com) `代码` - 列表 > 引用。你还可以使用@来通知其他用户。