Newbie’s information to Swift bundle supervisor command plugins

Introduction to Swift Package deal Supervisor plugins

Initially I might like to speak just a few phrases in regards to the new SPM plugin infrastructure, that was launched within the Swift 5.6 launch. The very first proposal describes the detailed design of the plugin API with some plugin examples, that are fairly helpful. Truthfully talking I used to be a bit to lazy to fastidiously learn by way of the complete documentation, it is fairly lengthy, however lengthy story brief, you possibly can create the next plugin varieties with the at present present APIs:

• Construct instruments – might be invoked by way of the SPM targets
• pre-build – runs earlier than the construct begins
• construct – runs throughout the construct

• Instructions – might be invoked by way of the command line
• supply code formatting – modifies the code inside bundle
• documentation technology – generate docs for the bundle
• customized – consumer outlined intentions

For the sake of simplicity on this tutorial I am solely going to jot down a bit in regards to the second class, aka. the command plugins. These plugins have been a bit extra fascinating for me, as a result of I needed to combine my deployment workflow into SPM, so I began to experiment with the plugin API to see how onerous it’s to construct such a factor. Seems it is fairly simple, however the developer expertise it is not that good. 😅

Constructing a supply code formatting plugin

The very very first thing I needed to combine with SPM was SwiftLint, since I used to be not capable of finding a plugin implementation that I may use I began from scratch. As a place to begin I used to be utilizing the instance code from the Package deal Supervisor Command Plugins proposal.

mkdir Instance
cd Instance
swift bundle init --type=library

I began with a model new bundle, utilizing the swift bundle init command, then I modified the Package deal.swift file in keeping with the documentation. I’ve additionally added SwiftLint as a bundle dependency so SPM can obtain & construct the and hopefully my customized plugin command can invoke the swiftlint executable when it’s wanted.

import PackageDescription

let bundle = Package deal(
    title: "Instance",
    platforms: [
        .macOS(.v10_15),
    ],
    merchandise: [
        .library(name: "Example", targets: ["Example"]),
        .plugin(title: "MyCommandPlugin", targets: ["MyCommandPlugin"]),
    ],
    dependencies: [
        .package(url: "https://github.com/realm/SwiftLint", branch: "master"),
    ],
    targets: [
        .target(name: "Example", dependencies: []),
        .testTarget(title: "ExampleTests", dependencies: ["Example"]),
       
        .plugin(title: "MyCommandPlugin",
                functionality: .command(
                    intent: .sourceCodeFormatting(),
                    permissions: [
                        .writeToPackageDirectory(reason: "This command reformats source files")
                    ]
                ),
                dependencies: [
                    .product(name: "swiftlint", package: "SwiftLint"),
                ]),
    ]
)

I’ve created a Plugins listing with a most important.swift file proper subsequent to the Sources folder, with the next contents.

import PackagePlugin
import Basis

@most important
struct MyCommandPlugin: CommandPlugin {
    
    func performCommand(context: PluginContext, arguments: [String]) throws {
        let device = attempt context.device(named: "swiftlint")
        let toolUrl = URL(fileURLWithPath: device.path.string)
        
        for goal in context.bundle.targets {
            guard let goal = goal as? SourceModuleTarget else { proceed }

            let course of = Course of()
            course of.executableURL = toolUrl
            course of.arguments = [
                "(target.directory)",
                "--fix",
               
            ]

            attempt course of.run()
            course of.waitUntilExit()
            
            if course of.terminationReason == .exit && course of.terminationStatus == 0 {
                print("Formatted the supply code in (goal.listing).")
            }
            else {
                let drawback = "(course of.terminationReason):(course of.terminationStatus)"
                Diagnostics.error("swift-format invocation failed: (drawback)")
            }
        }
    }
}

The snippet above ought to find the swiftlint device utilizing the plugins context then it’s going to iterate by way of the obtainable bundle targets, filter out non source-module targets and format solely these targets that incorporates precise Swift supply information. The method object ought to merely invoke the underlying device, we will wait till the kid (swiftlint invocation) course of exists and hopefully we’re good to go. 🤞

Replace: kalKarmaDev advised me that it’s attainable to move the --in-process-sourcekit argument to SwiftLint, it will repair the underlying concern and the supply information are literally mounted.

I needed to listing the obtainable plugins & run my supply code linter / formatter utilizing the next shell instructions, however sadly looks as if the swiftlint invocation half failed for some unusual purpose.

swift bundle plugin --list
    swift bundle format-source-code #will not work, wants entry to supply information
    swift bundle --allow-writing-to-package-directory format-source-code

Looks as if there’s an issue with the exit code of the invoked swiftlint course of, so I eliminated the success verify from the plugin supply to see if that is inflicting the problem or not additionally tried to print out the executable command to debug the underlying drawback.

import PackagePlugin
import Basis

@most important
struct MyCommandPlugin: CommandPlugin {
    
    func performCommand(context: PluginContext, arguments: [String]) throws {
        let device = attempt context.device(named: "swiftlint")
        let toolUrl = URL(fileURLWithPath: device.path.string)
        
        for goal in context.bundle.targets {
            guard let goal = goal as? SourceModuleTarget else { proceed }

            let course of = Course of()
            course of.executableURL = toolUrl
            course of.arguments = [
                "(target.directory)",
                "--fix",
            ]

            print(toolUrl.path, course of.arguments!.joined(separator: " "))

            attempt course of.run()
            course of.waitUntilExit()
        }
    }
}

Deliberately made a small “mistake” within the Instance.swift supply file, so I can see if the swiftlint –fix command will remedy this concern or not. 🤔

public struct Instance {
    public non-public(set) var textual content = "Hi there, World!"

    public init() {
        let xxx :Int = 123
    }
}

Seems, once I run the plugin by way of the Course of invocation, nothing occurs, however once I enter the next code manually into the shell, it simply works.

/Customers/tib/Instance/.construct/arm64-apple-macosx/debug/swiftlint /Customers/tib/Instance/Assessments/Instance --fix
/Customers/tib/Instance/.construct/arm64-apple-macosx/debug/swiftlint /Customers/tib/Instance/Assessments/ExampleTests --fix

All proper, so we positively have an issue right here… I attempted to get the usual output message and error message from the operating course of, looks as if swiftlint runs, however one thing within the SPM infrastructure blocks the code adjustments within the bundle. After a number of hours of debugging I made a decision to provide a shot to swift-format, as a result of that is what the official docs counsel. 🤷‍♂️

import PackageDescription

let bundle = Package deal(
    title: "Instance",
    platforms: [
        .macOS(.v10_15),
    ],
    merchandise: [
        .library(name: "Example", targets: ["Example"]),
        .plugin(title: "MyCommandPlugin", targets: ["MyCommandPlugin"]),
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-format", exact: "0.50600.1"),
    ],
    targets: [
        .target(name: "Example", dependencies: []),
        .testTarget(title: "ExampleTests", dependencies: ["Example"]),
       
        .plugin(title: "MyCommandPlugin",
                functionality: .command(
                    intent: .sourceCodeFormatting(),
                    permissions: [
                        .writeToPackageDirectory(reason: "This command reformats source files")
                    ]
                ),
                dependencies: [
                    .product(name: "swift-format", package: "swift-format"),
                ]),
    ]
)

Modified each the Package deal.swift file and the plugin supply code, to make it work with swift-format.

import PackagePlugin
import Basis

@most important
struct MyCommandPlugin: CommandPlugin {
    
    func performCommand(context: PluginContext, arguments: [String]) throws {
        let swiftFormatTool = attempt context.device(named: "swift-format")
        let swiftFormatExec = URL(fileURLWithPath: swiftFormatTool.path.string)

        
        for goal in context.bundle.targets {
            guard let goal = goal as? SourceModuleTarget else { proceed }

            let course of = Course of()
            course of.executableURL = swiftFormatExec
            course of.arguments = [

                "--in-place",
                "--recursive",
                "(target.directory)",
            ]
            attempt course of.run()
            course of.waitUntilExit()

            if course of.terminationReason == .exit && course of.terminationStatus == 0 {
                print("Formatted the supply code in (goal.listing).")
            }
            else {
                let drawback = "(course of.terminationReason):(course of.terminationStatus)"
                Diagnostics.error("swift-format invocation failed: (drawback)")
            }
        }
    }
}

I attempted to run once more the very same bundle plugin command to format my supply information, however this time swift-format was doing the code formatting as an alternative of swiftlint.

swift bundle --allow-writing-to-package-directory format-source-code
// ... loading dependencies
Construct full! (6.38s)
Formatted the supply code in /Customers/tib/Linter/Assessments/ExampleTests.
Formatted the supply code in /Customers/tib/Linter/Sources/Instance.

Labored like a attraction, my Instance.swift file was mounted and the : was on the left aspect… 🎊

public struct Instance {
    public non-public(set) var textual content = "Hi there, World!"

    public init() {
        let xxx: Int = 123
    }
}

Yeah, I’ve made some progress, nevertheless it took me numerous time to debug this concern and I do not like the truth that I’ve to fiddle with processes to invoke different instruments… my intestine tells me that SwiftLint will not be following the usual shell exit standing codes and that is inflicting some points, perhaps it is spawning little one processes and that is the issue, I actually do not know however I do not needed to waste extra time on this concern, however I needed to maneuver ahead with the opposite class. 😅

Integrating the DocC plugin with SPM

As a primary step I added some dummy feedback to my Instance library to have the ability to see one thing within the generated documentation, nothing fancy just a few one-liners. 📖

public struct Instance {

    
    public non-public(set) var textual content = "Hi there, World!"
    
    
    public init() {
        let xxx: Int = 123
    }
}

I found that Apple has an official DocC plugin, so I added it as a dependency to my undertaking.

import PackageDescription

let bundle = Package deal(
    title: "Instance",
    platforms: [
        .macOS(.v10_15),
    ],
    merchandise: [
        .library(name: "Example", targets: ["Example"]),
        .plugin(title: "MyCommandPlugin", targets: ["MyCommandPlugin"]),
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-format", exact: "0.50600.1"),
        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),

    ],
    targets: [
        .target(name: "Example", dependencies: []),
        .testTarget(title: "ExampleTests", dependencies: ["Example"]),
       
        .plugin(title: "MyCommandPlugin",
                functionality: .command(
                    intent: .sourceCodeFormatting(),
                    permissions: [
                        .writeToPackageDirectory(reason: "This command reformats source files")
                    ]
                ),
                dependencies: [
                    .product(name: "swift-format", package: "swift-format"),
                ]),
    ]
)

Two new plugin instructions have been obtainable after I executed the plugin listing command.

swift bundle plugin --list

Tried to run the primary one, and fortuitously the doccarchive file was generated. 😊

swift bundle generate-documentation

Additionally tried to preview the documentation, there was a notice in regards to the --disable-sandbox flag within the output, so I merely added it to my authentic command and…

swift bundle preview-documentation 

swift bundle --disable-sandbox preview-documentation

Magic. It labored and my documentation was obtainable. Now that is how plugins ought to work, I beloved this expertise and I actually hope that an increasing number of official plugins are coming quickly. 😍

Constructing a customized intent command plugin

I needed to construct a small executable goal with some bundled sources and see if a plugin can deploy the executable binary with the sources. This could possibly be very helpful once I deploy feather apps, I’ve a number of module bundles there and now I’ve to manually copy the whole lot… 🙈

import PackageDescription

let bundle = Package deal(
    title: "Instance",
    platforms: [
        .macOS(.v10_15),
    ],
    merchandise: [
        .library(name: "Example", targets: ["Example"]),
        .executable(title: "MyExample", targets: ["MyExample"]),
        .plugin(title: "MyCommandPlugin", targets: ["MyCommandPlugin"]),
        .plugin(title: "MyDistCommandPlugin", targets: ["MyDistCommandPlugin"]),
    ],
    dependencies: [
        .package(url: "https://github.com/apple/swift-format", exact: "0.50600.1"),
        .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),

    ],
    targets: [
        .executableTarget(name: "MyExample",
                          resources: [
                            .copy("Resources"),
                          ], plugins: [
                            
                          ]),
        .goal(title: "Instance", dependencies: []),
        .testTarget(title: "ExampleTests", dependencies: ["Example"]),
       
        .plugin(title: "MyCommandPlugin",
                functionality: .command(
                    intent: .sourceCodeFormatting(),
                    permissions: [
                        .writeToPackageDirectory(reason: "This command reformats source files")
                    ]
                ),
                dependencies: [
                    .product(name: "swift-format", package: "swift-format"),
                ]),
        
        .plugin(title: "MyDistCommandPlugin",
                functionality: .command(
                    intent: .customized(verb: "dist", description: "Create dist archive"),
                    permissions: [
                        .writeToPackageDirectory(reason: "This command deploys the executable")
                    ]
                ),
                dependencies: [
                ]),
    ]
)

As a primary step I created a brand new executable goal referred to as MyExample and a brand new MyDistCommandPlugin with a customized verb. Contained in the Sources/MyExample/Assets folder I’ve positioned a easy check.json file with the next contents.

{
    "success": true
}

The most important.swift file of the MyExample goal seems to be like this. It simply validates that the useful resource file is out there and it merely decodes the contents of it and prints the whole lot to the usual output. 👍

import Basis

guard let jsonFile = Bundle.module.url(forResource: "Assets/check", withExtension: "json") else {
    fatalError("Bundle file not discovered")
}
let jsonData = attempt Knowledge(contentsOf: jsonFile)

struct Json: Codable {
    let success: Bool
}

let json = attempt JSONDecoder().decode(Json.self, from: jsonData)

print("Is success?", json.success)

Contained in the Plugins folder I’ve created a most important.swift file below the MyDistCommandPlugin folder.

import PackagePlugin
import Basis

@most important
struct MyDistCommandPlugin: CommandPlugin {
    
    func performCommand(context: PluginContext, arguments: [String]) throws {
        
        
    }
}

Now I used to be in a position to re-run the swift bundle plugin --list command and the dist verb appeared within the listing of accessible instructions. Now the one query is: how can we get the artifacts out of the construct listing? Thankfully the third instance of the instructions proposal is kind of comparable.

import PackagePlugin
import Basis

@most important
struct MyDistCommandPlugin: CommandPlugin {
    
    func performCommand(context: PluginContext, arguments: [String]) throws {
        let cpTool = attempt context.device(named: "cp")
        let cpToolURL = URL(fileURLWithPath: cpTool.path.string)

        let end result = attempt packageManager.construct(.product("MyExample"), parameters: .init(configuration: .launch, logging: .concise))
        guard end result.succeeded else {
            fatalError("could not construct product")
        }
        guard let executable = end result.builtArtifacts.first(the place : { $0.type == .executable }) else {
            fatalError("could not discover executable")
        }
        
        let course of = attempt Course of.run(cpToolURL, arguments: [
            executable.path.string,
            context.package.directory.string,
        ])
        course of.waitUntilExit()

        let exeUrl = URL(fileURLWithPath: executable.path.string).deletingLastPathComponent()
        let bundles = attempt FileManager.default.contentsOfDirectory(atPath: exeUrl.path).filter { $0.hasSuffix(".bundle") }

        for bundle in bundles {
            let course of = attempt Course of.run(cpToolURL, arguments: ["-R",
                                                                    exeUrl.appendingPathComponent(bundle).path,
                                                                    context.package.directory.string,
                                                                ])
            course of.waitUntilExit()
        }
    }
}

So the one drawback was that I used to be not in a position to get again the bundled sources, so I had to make use of the URL of the executable file, drop the final path element and browse the contents of that listing utilizing the FileManager to get again the .bundle packages within that folder.

Sadly the builtArtifacts property solely returns the executables and libraries. I actually hope that we will get help for bundles as nicely sooner or later so this hacky answer might be prevented for good. Anyway it really works simply high-quality, however nonetheless it is a hack, so use it fastidiously. ⚠️

swift bundle --allow-writing-to-package-directory dist
./MyExample 

I used to be in a position to run my customized dist command with out additional points, in fact you need to use extra arguments to customise your plugin or add extra flexibility, the examples within the proposal are just about okay, nevertheless it’s fairly unlucky that there isn’t any official documentation for Swift bundle supervisor plugins simply but. 😕

Conclusion

Studying about command plugins was enjoyable, however to start with it was annoying as a result of I anticipated a bit higher developer expertise relating to the device invocation APIs. In abstract I can say that that is just the start. It is similar to the async / await and actors addition to the Swift language. The function itself is there, it is largely able to go, however not many builders are utilizing it each day. These items would require time and hopefully we will see much more plugins afterward… 💪