Documentation: BuildToolPlugin example uses wrong type for executable

[ADKaster]

With swift from swiftly main-snapshot-2025-06-03, BuildCommand expects executable to be a URL.

swift-package-manager/Sources/PackagePlugin/Command.swift

Lines 45 to 53 in ff7ea75

	@available(_PackageDescription, introduced: 6.0)
	case buildCommand(
	displayName: String?,
	executable: URL,
	arguments: [String],
	environment: [String: String] = [:],
	inputFiles: [URL] = [],
	outputFiles: [URL] = []
	)

Swift version 6.2-dev (LLVM b5d039be1fbae13, Swift 4fb4945ab972c85)
Target: x86_64-unknown-linux-gnu
Build config: +assertions

The example in Plugins.md passes a Path instead.

https://github.com/swiftlang/swift-package-manager/blob/ff7ea75b95e503bd3f22fcf8cf09e274561c3c10/Documentation/Plugins.md#implementing-the-build-tool-plugin-script

return .buildCommand(
    displayName: "Generating \(outputName) from \(inputPath.lastComponent)",
=>  executable: try context.tool(named: "SomeTool").path,
    arguments: [ "--verbose", "\(inputPath)", "\(outputPath)" ],
    inputFiles: [ inputPath, ],
    outputFiles: [ outputPath ]
)

Trying this pattern in my own code is a hard error.

Swift version 6.2-dev (LLVM b5d039be1fbae13, Swift 4fb4945ab972c85)
Target: x86_64-unknown-linux-gnu
/home/andrew/ladybird-org/htmlparser-swift/Plugins/GenerateNamedCharacterReferencesPlugin/main.swift:35:89: error: cannot convert value of type 'Path' to expected argument type 'URL'
33 |             .buildCommand(
34 |                 displayName: "Generate Named Character References",
35 |                 executable: try context.tool(named: "GenerateNamedCharacterReferences").path,
   |                                                                                         `- error: cannot convert value of type 'Path' to expected argument type 'URL'
36 |                 arguments: [
37 |                     "--generated-header-path", outputHeader.path,
error: build planning stopped due to build-tool plugin failures

[jakepetroules]

The Path based API was deprecated in favor of the URL based API in tools version 6.0. We should update the documentation.

That said, the old API should still work (just with a warning). Your code might be selecting the wrong overload. executable, inputPaths, and outputPaths must all be URLs or all Paths.

[plemarquand]

Worth noting that right now swift package init --type build-tool-plugin generates code that uses the old Path APIs and so compiles with warnings (#8797). #8801 aims to fix that.

[ADKaster]

Your code might be selecting the wrong overload. executable, inputPaths, and outputPaths must all be URLs or all Paths.

That explains my error exactly. inputPaths and outputPaths were both lists of URLs, as I had already converted the input and output variables to URLs to get rid of the deprecation warnings about context.pluginWorkDirectory and target.directory. The linked example in the original post doesn't really use both of those properties, but the one I found in GitHub/google search does.