|
| 1 | +# Swift Package Plugins |
| 2 | + |
| 3 | +Plugins were introduced for Swift Package Manager in Swift 5.6 (Xcode 13.4) and they have great potential to streamline your developer experience. |
| 4 | + |
| 5 | +If you are new to Plugins, be sure to check out some more general introductions from the resources below: |
| 6 | + |
| 7 | +- [Meet Swift Package plugins - Apple WWDC 2022](https://developer.apple.com/videos/play/wwdc2022/110359/) |
| 8 | +- [Create Swift Package plugins - Apple WWDC 2022](https://developer.apple.com/videos/play/wwdc2022/110401/) |
| 9 | + |
| 10 | +If you want to learn how to use Swift Package plugins with CreateAPI, we've explored use cases with both Command and Build Tool plugins. |
| 11 | + |
| 12 | +> **Warning**: Plugins are a new concept, and we're still learning about them ourself. Expect this documentation to change frequently so be sure to check back for new best practices. |
| 13 | +
|
| 14 | +## Depending on `create-api` |
| 15 | + |
| 16 | +While there are different types of plugins, you are always going to need the `create-api` cli as a dependency. |
| 17 | + |
| 18 | +You can do this by adding the CreateAPI package as a dependency just like you would with any other library but this means that you need to compile it each time, which isn't ideal. |
| 19 | + |
| 20 | +Instead, you can add your own target that links to our published Artifact Bundle to bring in a precompiled version of the tool. |
| 21 | + |
| 22 | +> **Note**: Currently, our Artifact Bundle only includes the precompiled binary for macOS meaning that there is no Linux support. |
| 23 | +
|
| 24 | +To add a new `binaryTarget` to your package, you need two pieces of information: |
| 25 | + |
| 26 | +1. The url to the artifact bundle |
| 27 | +2. The checksum of the bundle |
| 28 | + |
| 29 | +You can find all of this in the [release notes](https://github.com/CreateAPI/CreateAPI/releases/latest). |
| 30 | + |
| 31 | +In your **Package.swift**, add the following to your `targets` array: |
| 32 | + |
| 33 | +```swift |
| 34 | +.binaryTarget( |
| 35 | + name: "create-api", |
| 36 | + url: "https://github.com/CreateAPI/CreateAPI/releases/download/x.x.x/create-api.artifactbundle.zip", |
| 37 | + checksum: "ffffffffff" |
| 38 | +) |
| 39 | +``` |
| 40 | + |
| 41 | +Replace the `url` and `checksum` with the values for the release of your choice. |
| 42 | + |
| 43 | +## Writing a Plugin |
| 44 | + |
| 45 | +- [Command Plugin](#command-plugin) |
| 46 | +- [Build Tool Plugin](#build-tool-plugin) |
| 47 | + |
| 48 | +### Command Plugin |
| 49 | + |
| 50 | +A command plugin can be invoked on demand via the `swift package` command. |
| 51 | + |
| 52 | +Depending on your usage, you might then write a plugin that just invokes the `create-api` cli with the appropriate options and arguments, or you might do something more complex like invoke the command multiple times for multiple different modules. It's entirely up to you. |
| 53 | + |
| 54 | +Below is a basic example of a `CommandPlugin`: |
| 55 | + |
| 56 | +**Plugins/GenerateAPI/Plugin.swift** |
| 57 | +```swift |
| 58 | +import Foundation |
| 59 | +import PackagePlugin |
| 60 | + |
| 61 | +@main |
| 62 | +struct Plugin: CommandPlugin { |
| 63 | + func performCommand(context: PluginContext, arguments: [String]) async throws { |
| 64 | + let createAPI = try context.tool(named: "create-api") |
| 65 | + let workingDirectory = context.package.directory.appending("Sources", "MyAPI") |
| 66 | + |
| 67 | + let process = Process() |
| 68 | + process.currentDirectoryURL = URL(fileURLWithPath: workingDirectory.string) |
| 69 | + process.executableURL = URL(fileURLWithPath: createAPI.path.string) |
| 70 | + process.arguments = [ |
| 71 | + "generate", |
| 72 | + "schema.json", |
| 73 | + "--config", ".create-api.yml", |
| 74 | + "--output", "Generated" |
| 75 | + ] |
| 76 | + |
| 77 | + try process.run() |
| 78 | + process.waitUntilExit() |
| 79 | + } |
| 80 | +} |
| 81 | +``` |
| 82 | + |
| 83 | +**Package.swift** |
| 84 | +```swift |
| 85 | +// swift-tools-version:5.6 |
| 86 | +import PackageDescription |
| 87 | + |
| 88 | +let package = Package( |
| 89 | + name: "MyPackage", |
| 90 | + platforms: [.iOS(.v13), .macOS(.v10_15)], |
| 91 | + products: [.library(name: "MyAPI", targets: ["MyAPI"])], |
| 92 | + dependencies: [ |
| 93 | + // ... |
| 94 | + ], |
| 95 | + targets: [ |
| 96 | + .target( |
| 97 | + name: "MyAPI", |
| 98 | + exclude: ["schema.json", ".create-api.yml"] |
| 99 | + ), |
| 100 | + .binaryTarget( |
| 101 | + name: "create-api", |
| 102 | + url: "https://github.com/CreateAPI/CreateAPI/releases/download/0.0.5/create-api.artifactbundle.zip", |
| 103 | + checksum: "89c75ec3b2938d08b961b94e70e6dd6fa0ff52a90037304d41718cd5fb58bd24" |
| 104 | + ), |
| 105 | + .plugin( |
| 106 | + name: "CreateAPI", |
| 107 | + capability: .command( |
| 108 | + intent: .custom( |
| 109 | + verb: "generate-api", |
| 110 | + description: "Generates the OpenAPI entities and paths using CreateAPI" |
| 111 | + ), |
| 112 | + permissions: [ |
| 113 | + .writeToPackageDirectory(reason: "To output the generated source code") |
| 114 | + ] |
| 115 | + ), |
| 116 | + dependencies: [ |
| 117 | + .target(name: "create-api") |
| 118 | + ] |
| 119 | + ) |
| 120 | + ] |
| 121 | +) |
| 122 | +``` |
| 123 | + |
| 124 | + You could then invoke the plugin like so: |
| 125 | + |
| 126 | +```bash |
| 127 | +$ swift package --allow-writing-to-package-directory generate-api |
| 128 | +``` |
| 129 | + |
| 130 | +In the above example, the plugin will call `create-api generate` within the **Sources/MyAPI/** directory where it loads the **schema.json** and **.create-api.yml** files and outputs the sources inline. You can then review the output and commit them etc. |
| 131 | + |
| 132 | +### Build Tool Plugin |
| 133 | + |
| 134 | +A build tool plugin works slightly differently. Instead of manually running it through the `swift package` command, its run as part of the build process meaning that you can do things such as generate the source code only when required and avoid having to check it into source control. |
| 135 | + |
| 136 | +Below is a basic example of a `BuildToolPlugin`: |
| 137 | + |
| 138 | +**Plugins/GenerateAPI/Plugin.swift** |
| 139 | +```swift |
| 140 | +import Foundation |
| 141 | +import PackagePlugin |
| 142 | + |
| 143 | +@main |
| 144 | +struct Plugin: BuildToolPlugin { |
| 145 | + func createBuildCommands(context: PluginContext, target: Target) async throws -> [Command] { |
| 146 | + let schema = context.package.directory.appending("schema.yml") |
| 147 | + let config = context.package.directory.appending(".create-api.yml") |
| 148 | + let output = context.pluginWorkDirectory |
| 149 | + |
| 150 | + return [ |
| 151 | + .buildCommand( |
| 152 | + displayName: "Generating API", |
| 153 | + executable: try context.tool(named: "create-api").path, |
| 154 | + arguments: [ |
| 155 | + "generate", |
| 156 | + schema, |
| 157 | + "--output", output, |
| 158 | + "--config", config, |
| 159 | + "--config-option", "module=\(target.name)", |
| 160 | + "--config-option", "mergeSources=true" |
| 161 | + ], |
| 162 | + inputFiles: [ |
| 163 | + schema, |
| 164 | + config |
| 165 | + ], |
| 166 | + outputFiles: [ |
| 167 | + output.appending("Paths.swift"), |
| 168 | + output.appending("Entities.swift") |
| 169 | + ] |
| 170 | + ) |
| 171 | + ] |
| 172 | + } |
| 173 | +} |
| 174 | +``` |
| 175 | + |
| 176 | +**Package.swift** |
| 177 | +```swift |
| 178 | +// swift-tools-version: 5.6 |
| 179 | +import PackageDescription |
| 180 | + |
| 181 | +let package = Package( |
| 182 | + name: "MyPackage", |
| 183 | + platforms: [.iOS(.v13), .macOS(.v10_15)], |
| 184 | + products: [.library(name: "MyAPI", targets: ["MyAPI"])], |
| 185 | + dependencies: [ |
| 186 | + // ... |
| 187 | + ], |
| 188 | + targets: [ |
| 189 | + .target( |
| 190 | + name: "MyAPI", |
| 191 | + dependencies: [ |
| 192 | + .target(name: "GenerateAPI"), |
| 193 | + // ... |
| 194 | + ] |
| 195 | + ), |
| 196 | + .binaryTarget( |
| 197 | + name: "create-api", |
| 198 | + url: "https://github.com/CreateAPI/CreateAPI/releases/download/0.0.5/create-api.artifactbundle.zip", |
| 199 | + checksum: "89c75ec3b2938d08b961b94e70e6dd6fa0ff52a90037304d41718cd5fb58bd24" |
| 200 | + ), |
| 201 | + .plugin( |
| 202 | + name: "GenerateAPI", |
| 203 | + capability: .buildTool(), |
| 204 | + dependencies: [ |
| 205 | + .target(name: "create-api") |
| 206 | + ] |
| 207 | + ) |
| 208 | + ] |
| 209 | +) |
| 210 | +``` |
| 211 | + |
| 212 | +While there are some similarities to command plugins, the build tool plugin is marked as a dependency to the relevant target (`MyAPI`) and the plugin returns a build command provides to the build system so that it can determine if it needs to run or not. It does this by checking both the defined `inputs` and `outputs`. It the outputs are missing, or the inputs have changed, it'll run the `create-api generate` command and write the outputs into `pluginWorkDirectory`. |
| 213 | + |
| 214 | +This is powerful, because it enables you to modify the schema or configuration file inside Xcode, hit <kbd>⌘</kbd> + <kbd>B</kbd> and see your changes reflected instantaneously. It does however have some downsides because it is not easy to find the generated sources and can make debugging schema/generation issues tricker. |
0 commit comments