Swift Packageプラグインを作成する

Swift Packageプラグインを作成する

開発ワークフローをカスタマイズします。Swiftで独自のパッケージプラグインを作成する方法をご覧ください。PackagePlugin APIでソースコードを生成したりリリースタスクを自動化したりして、Xcodeの機能を拡張する方法をはじめ、優れたプラグインを作成するベストプラクティスを紹介します。

リソース
- - HDビデオ
  - SDビデオ
関連ビデオ

WWDC22
WWDC21
- SwiftUI Appのローカライズ
WWDC20
- Swiftパッケージ：リソースとローカリゼーション
WWDC19
- Swiftパッケージを作成する
ダウンロード

こんにちはBorisです「Swift Packageプラグインを作成する」へようこそ
私たちはXcode 11で Swiftパッケージのサポートを導入しライブラリをソースコードとして配布する簡単なアプローチを提供します Xcode 14では Swiftパッケージプラグインによってソースコードの生成やリリース作業の自動化などの開発ワークフローにコンポーネントを構造化しての共有と同じ優れた方法を提供したいと考えていますまず講演の概要を説明しますプラグインの基本を学んだ後デモで初めてカスタムコマンドプラグインを構築します次にプラグインの作成について詳しく見ていきさらにデモでインビルドとプリビルドの両方のコマンドプラグインを作成していきます
パッケージプラグインはパッケージマニフェストと同様に PackagePlugin API を使用する Swift コードですプラグインは明確に定義された拡張ポイントを通じて XcodeやSwift パッケージマネージャの機能を拡張することができます
パッケージプラグインの仕組みはどうでしょう？ Xcodeはプラグインをコンパイルして実行しますプラグインは利用可能な実行ファイルと入力ファイルに関する情報を使用してコマンドを作成し必要に応じて実行するためにXcodeに伝達し返します
パッケージプラグインはソースコードやリソースファイルを生成するなどビルド前またはビルド中に実行されるカスタムビルドタスクを提供することができます
SwiftPMのコマンドラインインターフェースにカスタムコマンドを追加したり Xcodeにメニュー項目を追加したりもできますプラグインの基本については「Swift Packageプラグインの紹介」を見ることをお勧めしますしパッケージが全く初めてという場合には WWDC19「Swiftパッケージを作成する」のセッションを見るとよいでしょう
最初のカスタムコマンドプラグインの構築を見てみましょう
Swiftオープンソースのtools-support-core パッケージで作業しているのですがプロジェクトへの貢献者をリストアップするテキストファイルを追加したいのですがどうすれば良いでしょうまたパッケージのGit履歴から必要に応じて再生成したいです
これまではシェルスクリプトや makefileを書いていたかもしれませんがカスタムコマンドプラグインを作って Xcodeを離れることなくファイルを再生成できるようにしたいと思います
まずプラグインのディレクトリ構造を作成する必要がありますパッケージのコンテキストメニューを開き新規フォルダを選択して既存のSourcesやTestsと同様にPluginsというトップレベルフォルダを作成します
次にプラグインターゲット用に GenerateContributors という名前の別のネストしたフォルダを作成します
そしてその中に新しいファイルを作り「plugin.swift」という名前を付けます
次にパッケージマニフェストを変更して新しいターゲットをそこに宣言する必要がありますその前にこのパッケージのツールバージョンを 5.6に上げる必要がありますプラグインはこのバージョンからしか利用できないからです
次にプラグインターゲットを挿入します
ここで新しいマニフェストAPI を見てみましょう
ソースモジュールのターゲットと同様に Plugins フォルダ内のフォルダに対応するプラグインターゲットを作成します
これは Xcodeのメニュー項目としてだけでなくフォルダの名前としても関連性のある名前を取得します
ケーパビリティを指定するのにどのような拡張ポイントを使えば良いのかインテントではプラグインが行うことの説明と同様に
インテントではプラグインが行うことの説明と同様に SwiftPM のコマンドライン用の動詞を定義でき最後にプラグインが必要とするパーミッションを宣言できます
今回はパッケージのルートに新しいファイルを書き込むのでそのディレクトリに書き込むパーミッションが必要です理由文字列はプラグインのユーザーに表示され OS自体のパーミッションの仕組みと同様にパーミッションを許可するか分かるようになっていますプラグインを宣言したところで実際に実装してみましょう
このプラグインはコミット履歴を取得するため Gitにシェルアウトします外部のGitコマンドの standardoutから履歴を読みその結果を解析して最後にテキストファイルに書き出します
先ほど作成したプラグインソースファイルを開き PackagePluginをインポートします
これはPackageDescriptionのような組み込みモジュールでプラグインを実装するために使用できるAPIにアクセスが可能になります
GenerateContributors構造体を定義し CommandPluginに適合させます
プロトコルを実装するための足りないスタブを取得する fix-itを受け付けますこの構造体はプラグイン実行ファイルのメイン関数となるため @mainとしてマークする必要があります
performCommandはコマンドのエントリポイントで 2つの引数を受け取ります contextは解決されたパッケージグラフや実行されているコンテキストに関するその他の情報へのアクセスを提供し引数も同様に提供しますカスタムコマンドはユーザによって呼び出されるため引数という形で入力を与えることができます今回は単純なコマンドを作成するので実際にはユーザに何のオプションも提供しません
コミット履歴の情報を取得するために gitにシェルアウトしそのためにProcess APIを使いたいので Foundationをインポートしています
次にプロセスインスタンスを定義しいくつかのフォーマット引数を指定して git log を実行するように設定します
プロセスの出力を取り込むためのパイプを作成する必要がありますあとは実行し終了するのを待つだけです
処理が終了したらパイプからすべてのデータを読み込んですべてのgitログが出力される文字列に変換します
文字列操作をして出力を重複のないリストに切り詰め最後に「CONTRIBUTORS.txt」というファイルに書き出すことができますカスタムコマンドはパッケージのルートディレクトリで実行されるのでそこにファイルを格納します
保存した後プロジェクトナビゲータでパッケージを右クリックするとコンテキストメニューにコマンドの新しい項目が表示されます実行しましょう！
次のダイアログではプラグインの入力となるパッケージやターゲット引数を選択できますがこのプラグインはこれらオプションに反応しないので Runをクリックします
次に先ほどのマニフェストで定義したパーミッションが求められますプラグインは自分で書いただけなのでそのまま実行してもいいのですが信頼できるプラグインにだけ特別なパーミッションを与た方が良いです
実行後 CONTRIBUTORS.txt ファイルがプロジェクトナビゲータに表示されます
さて最初のプラグインでXcodeを拡張したのでプラグインの仕組みと作成する際の注意点についてもう少し深く掘り下げてみましょう
パッケージプラグインはパッケージマニフェスト自体の評価と同様にサンドボックス内で実行されますネットワークアクセスやプラグイン自身のワークディレクトリ以外の非一時的な場所への書き込みは禁止されていますカスタムコマンドはオプションとして先に示したようにパッケージのルートディレクトリへの書き込みを宣言できます既存のサードパーティツールをラッピングする場合生成されたファイルの書き込み先を設定するなどサンドボックスモデルに限定する方法を検討する必要があるかもしれません
最初にプラグインの種類をお話したのでカスタムコマンドとビルドツールのどちらが問題を解決するのに適しているかは明らかだと思いますがここではビルドツールのプラグインの構造について見ていきましょう
これらのプラグインはビルド中の実行ファイルの説明やビルド中の適切なタイミングでの作業のスケジューリングに役立つ入出力を指定することでビルドシステムを拡張することが可能です
Xcodeプロジェクトで実行スクリプトのフェーズを作成している方はここでの基本をご存知かもしれません
またビルドツールプラグインには 2つの種類がありますここで重要なのはツールに定義された出力があるかどうかです
もしそうならインビルドコマンドを作成して出力が入力に比べて古くなった場合にビルドシステムによって自動的に再実行されるようにする必要があります明確な出力がない場合はビルドの開始時に実行するビルド前コマンドを作成することができますこのためプレビルドコマンドで高価な作業をすることに注意するかユースケースに適した結果をキャッシュするカスタム戦略を考え出す必要があります
2つ目のデモでは作業中の異なるツール間で共有したいアイコンをカプセル化した新しいライブラリを作成したいと思います
さっそくテンプレートから新しいパッケージを作成し「IconLibrary」と名付けましょうそしてすでに持っているアイコンアセットをライブラリのターゲットにドラッグします基本的なSwiftUIのビューとプレビューを私のライブラリに追加してみましょうまず必要最低限のデプロイメントターゲットをマニフェストに追加する必要があります
次にその基本的な表示とプレビューを実際に追加してみましょうここでは先ほどドラッグしたアセットを使用します
ここで文字列を扱う代わりにこれらの画像を参照するためのタイプセーフな方法があればいいですねこれはアセットカタログを見てそれに基づいていくつかの Swift コードを生成するビルド中のコマンドプラグインのための素晴らしい使用例のように思えます Finderでアセットカタログを見てプラグインに必要な情報を抽出する方法を考えてみましょう
各画像はアセット名を持つ独自の imagesetディレクトリを取得します...
そして基本的な内容を記述した JSONファイルがあります
インビルドコマンドは実行する実行ファイルとその入出力の説明を提供するという点でカスタムコマンドと少し異なる動作をします
実行ファイルはシステムから提供されるものサードパーティのパッケージプラグイン用にオーダーメイドで作成できますここでは 3つ目のアプローチをとりたいと思います
プラグインはビルドプロセスの開始時に実行されビルドグラフの計算に参加します
それを元に実行ファイルがビルド実行の一部としてスケジュールされます
さてビルドしている実行ファイルに戻りますアセットカタログの各画像に対してコンパイル時の定数を持ちたいのでそれぞれの画像に対して正しい文字列を覚える代わりに Swiftのシンボルとしてそれらを自動完了させることができます
アセットカタログのディレクトリの内容をループしてすべての画像セットを見つけたいのです各画像セットについてそのメタデータを解析し実際に画像が含まれているかそのためにコードを生成する必要があるかを判断します
そしてコードを生成しファイルに書き込めますこれらのファイルはプラグインの出力として宣言されているのでプラグインが適用されているターゲットのビルドに自動的に組み込まれます
プラグインと実行ファイル間の通信は引数で行うので引数を処理する方法が必要になります
最初の引数は処理中のアセットカタログへのパスで 2番目の引数は生成されたコード用にプラグインが提供するパスとなります
次に contents.jsonファイルをデコードするモデルオブジェクトが必要です
Swiftに内蔵されているJSONのデコードを使うため Decodableを使用しています
我々が関心を持つ情報は画像リストとそのファイル名だけで各ピクセル密度の画像が存在しないかもしれないので任意となりますここでは単純化した方法で文字列を積み上げるだけでコードを生成することにします必要なフレームワークである Foundation と SwiftUI をインポートして開始します
アセットカタログのディレクトリの内容をループしてすべての画像セットを見つけます次に JSONをパースする必要がありますファイル名は入力パラメータを使用します Foundationの「JSONDecoder」 APIを使ってデコードしています
関心を持つべき主な情報は与えられた画像セットに対して定義された画像が存在するかということですこれは空でないファイル名を持つ画像が少なくとも1つあるかどうかをチェックすることによって決定されます与えられた画像セットに画像がある場合パッケージのバンドルからその画像をロードするSwiftUI画像を生成したいと思います
ビルドシステムがリソースを持つ各パッケージに対して作成するリソースバンドルであるモジュールバンドルから与えられた画像をロードする各画像のベース名を持つ文字列を構築することで行っています
引数で与えられた生成されたコードをファイルに書き込むことで実行ファイルの作業をまとめることができます
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 <%ae>%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