diff --git a/Sources/PackagePlugin/ArgumentExtractor.swift b/Sources/PackagePlugin/ArgumentExtractor.swift index 4b39c9eba6b..d99f12dd5a8 100644 --- a/Sources/PackagePlugin/ArgumentExtractor.swift +++ b/Sources/PackagePlugin/ArgumentExtractor.swift @@ -10,12 +10,21 @@ // //===----------------------------------------------------------------------===// -/// A rudimentary helper for extracting options and flags from a string list representing command line arguments. The idea is to extract all known options and flags, leaving just the positional arguments. This does not handle well the case in which positional arguments (or option argument values) happen to have the same name as an option or a flag. It only handles the long `--` form of options, but it does respect `--` as an indication that all remaining arguments are positional. +/// A rudimentary helper for extracting options and flags from a list of strings that represent command line arguments. +/// +/// Create the extractor with the full command line arguments provided, then extract all known +/// options and flags, which leaves the positional arguments. +/// +/// This does not handle the case where positional arguments (or optional argument values) have the same +/// name as an option or a flag. It only handles the long form of options, not short forms, for example: `--`, not `-n`. +/// It respects an argument that consists of two hyphens (`--`) as an indication that all remaining arguments are positional. public struct ArgumentExtractor { private var args: [String] private let literals: [String] - /// Initializes a ArgumentExtractor with a list of strings from which to extract flags and options. If the list contains `--`, any arguments that follow it are considered to be literals. + /// Creates an argument extractor with a list of strings from which to extract flags and options. + /// + /// If the list contains `--`, any arguments that follow it are considered positional arguments. public init(_ arguments: [String]) { // Split the array on the first `--`, if there is one. Everything after that is a literal. let parts = arguments.split(separator: "--", maxSplits: 1, omittingEmptySubsequences: false) @@ -23,7 +32,7 @@ public struct ArgumentExtractor { self.literals = Array(parts.count == 2 ? parts[1] : []) } - /// Extracts options of the form `-- ` or `--=` from the remaining arguments, and returns the extracted values. + /// Extracts options of the form `-- ` or `--=` from the remaining arguments and returns the extracted values. public mutating func extractOption(named name: String) -> [String] { var values: [String] = [] var idx = 0 @@ -66,12 +75,16 @@ public struct ArgumentExtractor { return count } - /// Returns any unextracted flags or options (based strictly on whether remaining arguments have a "--" prefix). + /// Returns any unextracted flags or options. + /// + /// This is based strictly on whether remaining arguments have a `--` prefix. public var unextractedOptionsOrFlags: [String] { return args.filter{ $0.hasPrefix("--") } } - /// Returns all remaining arguments, including any literals after the first `--` if there is one. + /// Returns all remaining arguments. + /// + /// The returned values include any positional arguments after the first `--`, if there is one. public var remainingArguments: [String] { return args + literals } diff --git a/Sources/PackagePlugin/Command.swift b/Sources/PackagePlugin/Command.swift index 3dd5e50b37d..ccad33cf98f 100644 --- a/Sources/PackagePlugin/Command.swift +++ b/Sources/PackagePlugin/Command.swift @@ -12,33 +12,35 @@ import Foundation -/// A command to run during the build, including executable, command lines, -/// environment variables, initial working directory, etc. All paths should be -/// based on the ones passed to the plugin in the target build context. +/// A command to run during the build. +/// +/// A command includes the executable, command lines, environment variables, initial working directory, and so on. +/// All paths should be based on the ones that SwiftPM passes to the plugin in the target build context. public enum Command { /// Returns a command that runs when any of its output files are needed by - /// the build, but out-of-date. + /// the build and are out-of-date. /// /// An output file is out-of-date if it doesn't exist, or if any input files /// have changed since the command was last run. /// /// - Note: the paths in the list of output files may depend on the list of /// input file paths, but **must not** depend on reading the contents of - /// any input files. Such cases must be handled using a `prebuildCommand`. + /// any input files. Use a `prebuildCommand`if the functionality of your plugin + /// requires you to read the contents of an input file. /// /// - parameters: /// - displayName: An optional string to show in build logs and other /// status areas. - /// - executable: The absolute path to the executable to be invoked. - /// - arguments: Command-line arguments to be passed to the executable. - /// - environment: Environment variable assignments visible to the + /// - executable: The absolute path to the executable to invoke. + /// - arguments: The command-line arguments for the executable. + /// - environment: Any environment variable assignments visible to the /// executable. - /// - inputFiles: Files on which the contents of output files may depend. + /// - inputFiles: A list of files on which the contents of output files may depend. /// Any paths passed as `arguments` should typically be passed here as /// well. - /// - outputFiles: Files to be generated or updated by the executable. + /// - outputFiles: A list of files to be generated or updated by the executable. /// Any files recognizable by their extension as source files - /// (e.g. `.swift`) are compiled into the target for which this command + /// (for example, `.swift`) are compiled into the target for which this command /// was generated as if in its source directory; other files are treated /// as resources as if explicitly listed in `Package.swift` using /// `.process(...)`. @@ -61,17 +63,18 @@ public enum Command { /// determine this list without first running the command, so /// instead of encoding that list, the caller supplies an /// `outputFilesDirectory` parameter, and all files in that - /// directory after the command runs are treated as output files. + /// directory after the command runs are treated as the output files + /// of the plugin. /// /// - parameters: /// - displayName: An optional string to show in build logs and other /// status areas. - /// - executable: The absolute path to the executable to be invoked. - /// - arguments: Command-line arguments to be passed to the executable. - /// - environment: Environment variable assignments visible to the executable. + /// - executable: The absolute path to the executable to invoke. + /// - arguments: The command-line arguments for the executable. + /// - environment: Any environment variable assignments visible to the executable. /// - outputFilesDirectory: A directory into which the command writes its - /// output files. Any files there recognizable by their extension as - /// source files (e.g. `.swift`) are compiled into the target for which + /// output files. The package manager compiles any files there recognizable by + /// their extension as source files (for example, `.swift`) into the target for which /// this command was generated as if in its source directory; other /// files are treated as resources as if explicitly listed in /// `Package.swift` using `.process(...)`. @@ -87,7 +90,7 @@ public enum Command { extension Command { /// Returns a command that runs when any of its output files are needed by - /// the build, but out-of-date. + /// the build and are out-of-date. /// /// An output file is out-of-date if it doesn't exist, or if any input files /// have changed since the command was last run. @@ -99,19 +102,23 @@ extension Command { /// - parameters: /// - displayName: An optional string to show in build logs and other /// status areas. - /// - executable: The absolute path to the executable to be invoked. - /// - arguments: Command-line arguments to be passed to the executable. + /// - executable: The absolute path to the executable to invoke. + /// - arguments: Command-line arguments for the executable. /// - environment: Environment variable assignments visible to the /// executable. /// - inputFiles: Files on which the contents of output files may depend. /// Any paths passed as `arguments` should typically be passed here as /// well. - /// - outputFiles: Files to be generated or updated by the executable. - /// Any files recognizable by their extension as source files - /// (e.g. `.swift`) are compiled into the target for which this command + /// - outputFiles: The files that the plugin generates or updates using the executable. + /// The package manager compiles any files recognizable by their extension as source files + /// (e.g. `.swift`) into the target for which this command /// was generated as if in its source directory; other files are treated /// as resources as if explicitly listed in `Package.swift` using /// `.process(...)`. + /// + /// @DeprecationSummary { + /// Use ``buildCommand(displayName:executable:arguments:environment:inputFiles:outputFiles:)-swift.enum.case`` instead. + /// } @available(_PackageDescription, deprecated: 6.0, message: "Use `URL` type instead of `Path`.") public static func buildCommand( displayName: String?, @@ -132,32 +139,33 @@ extension Command { } /// Returns a command that runs when any of its output files are needed - /// by the build, but out-of-date. + /// by the build and are out-of-date. /// /// An output file is out-of-date if it doesn't exist, or if any input /// files have changed since the command was last run. /// /// - Note: the paths in the list of output files may depend on the list /// of input file paths, but **must not** depend on reading the contents - /// of any input files. Such cases must be handled using a `prebuildCommand`. + /// of any input files. Use a `prebuildCommand`if the functionality of your plugin + /// requires you to read the contents of an input file. /// /// - parameters: /// - displayName: An optional string to show in build logs and other /// status areas. - /// - executable: The absolute path to the executable to be invoked. - /// - arguments: Command-line arguments to be passed to the executable. - /// - environment: Environment variable assignments visible to the executable. + /// - executable: The absolute path to the executable to invoke. + /// - arguments: The command-line arguments for the executable. + /// - environment: Any environment variable assignments visible to the executable. /// - workingDirectory: Optional initial working directory when the executable /// runs. - /// - inputFiles: Files on which the contents of output files may depend. + /// - inputFiles: A list of files on which the contents of output files may depend. /// Any paths passed as `arguments` should typically be passed here as well. - /// - outputFiles: Files to be generated or updated by the executable. + /// - outputFiles: A list of files to be generated or updated by the executable. /// Any files recognizable by their extension as source files - /// (e.g. `.swift`) are compiled into the target for which this command + /// (for example, `.swift`) are compiled into the target for which this command /// was generated as if in its source directory; other files are treated /// as resources as if explicitly listed in `Package.swift` using /// `.process(...)`. - @available(*, unavailable, message: "specifying the initial working directory for a command is not yet supported") + @available(*, unavailable, message: "specifying the initial working directory for a command is not supported") public static func buildCommand( displayName: String?, executable: Path, @@ -191,17 +199,18 @@ extension Command { /// - parameters: /// - displayName: An optional string to show in build logs and other /// status areas. - /// - executable: The absolute path to the executable to be invoked. - /// - arguments: Command-line arguments to be passed to the executable. - /// - environment: Environment variable assignments visible to the executable. - /// - workingDirectory: Optional initial working directory when the executable - /// runs. + /// - executable: The absolute path to the executable to invoke. + /// - arguments: The command-line arguments for the executable. + /// - environment: Any environment variable assignments visible to the executable. /// - outputFilesDirectory: A directory into which the command writes its /// output files. Any files there recognizable by their extension as - /// source files (e.g. `.swift`) are compiled into the target for which + /// source files (for example, `.swift`) are compiled into the target for which /// this command was generated as if in its source directory; other /// files are treated as resources as if explicitly listed in /// `Package.swift` using `.process(...)`. + /// @DeprecationSummary { + /// Use ``prebuildCommand(displayName:executable:arguments:environment:outputFilesDirectory:)-swift.enum.case`` instead. + /// } @available(_PackageDescription, deprecated: 6.0, message: "Use `URL` type instead of `Path`.") public static func prebuildCommand( displayName: String?, @@ -233,18 +242,18 @@ extension Command { /// - parameters: /// - displayName: An optional string to show in build logs and other /// status areas. - /// - executable: The absolute path to the executable to be invoked. - /// - arguments: Command-line arguments to be passed to the executable. - /// - environment: Environment variable assignments visible to the executable. + /// - executable: The absolute path to the executable to invoke. + /// - arguments: The command-line arguments for the executable. + /// - environment: Any environment variable assignments visible to the executable. /// - workingDirectory: Optional initial working directory when the executable /// runs. /// - outputFilesDirectory: A directory into which the command writes its /// output files. Any files there recognizable by their extension as - /// source files (e.g. `.swift`) are compiled into the target for which + /// source files (for example, `.swift`) are compiled into the target for which /// this command was generated as if in its source directory; other /// files are treated as resources as if explicitly listed in /// `Package.swift` using `.process(...)`. - @available(*, unavailable, message: "specifying the initial working directory for a command is not yet supported") + @available(*, unavailable, message: "specifying the initial working directory for a command is not supported") public static func prebuildCommand( displayName: String?, executable: Path, diff --git a/Sources/PackagePlugin/Context.swift b/Sources/PackagePlugin/Context.swift index 9e048079d32..5944e653af7 100644 --- a/Sources/PackagePlugin/Context.swift +++ b/Sources/PackagePlugin/Context.swift @@ -12,47 +12,52 @@ import Foundation -/// Provides information about the package for which the plugin is invoked, -/// as well as contextual information based on the plugin's stated intent -/// and requirements. +/// A collection of information about the package on which the package manager invokes the plugin, +/// as well as contextual information based on the plugin's intent and requirements. public struct PluginContext { - /// Information about the package to which the plugin is being applied. + /// Information about the package the plugin works on. public let package: Package /// The path of a writable directory into which the plugin or the build - /// commands it constructs can write anything it wants. This could include - /// any generated source files that should be processed further, and it - /// could include any caches used by the build tool or the plugin itself. - /// The plugin is in complete control of what is written under this di- - /// rectory, and the contents are preserved between builds. + /// commands can write files. /// - /// A plugin would usually create a separate subdirectory of this directory - /// for each command it creates, and the command would be configured to - /// write its outputs to that directory. The plugin may also create other + /// This could include + /// generated source files to processed further, as well as + /// any caches used by the build tool or the plugin. + /// The plugin is in complete control of what is written under this directory, + /// and the package manager preserves the contents between builds. + /// + /// A plugin may create a separate subdirectory + /// for each command it creates, with the command configured to + /// write its output to that directory. The plugin may also create other /// directories for cache files and other file system content that either /// it or the command will need. @available(_PackageDescription, deprecated: 6.0, renamed: "pluginWorkDirectoryURL") public let pluginWorkDirectory: Path - /// The path of a writable directory into which the plugin or the build - /// commands it constructs can write anything it wants. This could include - /// any generated source files that should be processed further, and it - /// could include any caches used by the build tool or the plugin itself. - /// The plugin is in complete control of what is written under this di- - /// rectory, and the contents are preserved between builds. + /// The URL of a writable directory into which the plugin or the build + /// commands it constructs can write anything it wants. /// - /// A plugin would usually create a separate subdirectory of this directory - /// for each command it creates, and the command would be configured to - /// write its outputs to that directory. The plugin may also create other + /// This could include + /// generated source files to processed further, as well as + /// any caches used by the build tool or the plugin. + /// The plugin is in complete control of what is written under this directory, + /// and the package manager preserves the contents between builds. + /// + /// A plugin may create a separate subdirectory + /// for each command it creates, with the command configured to + /// write its output to that directory. The plugin may also create other /// directories for cache files and other file system content that either /// it or the command will need. @available(_PackageDescription, introduced: 6.0) public let pluginWorkDirectoryURL: URL - /// Looks up and returns the path of a named command line executable tool. - /// The executable must be provided by an executable target or a binary + /// Looks up and returns the path of a named command line executable. + /// + /// The executable must be provided by an executable target or binary /// target on which the package plugin target depends. This function throws /// an error if the tool cannot be found. The lookup is case sensitive. + /// - Parameter name: The name of the executable to find. public func tool(named name: String) throws -> Tool { if let tool = self.accessibleTools[name] { // For PluginAccessibleTool.builtTool, the triples value is not saved, thus @@ -81,32 +86,33 @@ public struct PluginContext { throw PluginContextError.toolNotFound(name: name) } - /// A mapping from tool names to their paths and triples. Not directly available - /// to the plugin, but used by the `tool(named:)` API. + /// A map from tool names to their paths and triples. + /// + /// This is not directly available to the plugin, but is used by ``tool(named:)``. let accessibleTools: [String: (path: URL, triples: [String]?)] - /// The paths of directories of in which to search for tools that aren't in + /// The paths of directories in which to search for tools that aren't in /// the `toolNamesToPaths` map. @available(_PackageDescription, deprecated: 6.0, renamed: "toolSearchDirectoryURLs") let toolSearchDirectories: [Path] - /// The paths of directories of in which to search for tools that aren't in + /// The paths of directories in which to search for tools that aren't in /// the `toolNamesToPaths` map. @available(_PackageDescription, introduced: 6.0) let toolSearchDirectoryURLs: [URL] /// Information about a particular tool that is available to a plugin. public struct Tool { - /// Name of the tool (suitable for display purposes). + /// The name of the tool, suitable for display purposes. public let name: String - /// Full path of the built or provided tool in the file system. + /// The path of the tool in the file system. @available(_PackageDescription, deprecated: 6.0, renamed: "url") public var path: Path { get { _path } } - /// Full path of the built or provided tool in the file system. + /// The file URL of the tool in the file system. @available(_PackageDescription, introduced: 6.0) public let url: URL diff --git a/Sources/PackagePlugin/Diagnostics.swift b/Sources/PackagePlugin/Diagnostics.swift index 0d05eff2f92..25b03190d7b 100644 --- a/Sources/PackagePlugin/Diagnostics.swift +++ b/Sources/PackagePlugin/Diagnostics.swift @@ -10,17 +10,24 @@ // //===----------------------------------------------------------------------===// -/// Emits errors, warnings, and remarks to be shown as a result of running the -/// plugin. After emitting one or more errors, the plugin should return a +/// Emits errors, warnings, and remarks to show as a result of running the +/// plugin. +/// +/// After emitting one or more errors, a plugin should return a /// non-zero exit code. public struct Diagnostics { - /// Severity of the diagnostic. + /// The severity of the diagnostic. public enum Severity: String, Encodable { case error, warning, remark } /// Emits an error with a specified severity and message, and optional file path and line number. + /// - Parameters: + /// - severity: The severity of the diagnostic. + /// - description: The description of the diagnostic. + /// - file: The file responsible for the diagnostic, that defaults to `#file`. + /// - line: The line responsible for the diagnostic, that defaults to `#line`. public static func emit(_ severity: Severity, _ description: String, file: String? = #file, line: Int? = #line) { let message: PluginToHostMessage switch severity { @@ -35,22 +42,35 @@ public struct Diagnostics { try? pluginHostConnection.sendMessage(message) } - /// Emits an error with the specified message, and optional file path and line number. + /// Emits an error with the message you specify. + /// - Parameters: + /// - message: The description of the error. + /// - file: The file responsible for the diagnostic, that defaults to `#file`. + /// - line: The line responsible for the diagnostic, that defaults to `#line`. public static func error(_ message: String, file: String? = #file, line: Int? = #line) { self.emit(.error, message, file: file, line: line) } - /// Emits a warning with the specified message, and optional file path and line number. + /// Emits a warning with the message you specify. + /// - Parameters: + /// - message: The description of the warning. + /// - file: The file responsible for the diagnostic, that defaults to `#file`. + /// - line: The line responsible for the diagnostic, that defaults to `#line`. public static func warning(_ message: String, file: String? = #file, line: Int? = #line) { self.emit(.warning, message, file: file, line: line) } - /// Emits a remark with the specified message, and optional file path and line number. + /// Emits a remark with the message you specify. + /// - Parameters: + /// - message: The description of the remark. + /// - file: The file responsible for the diagnostic, that defaults to `#file`. + /// - line: The line responsible for the diagnostic, that defaults to `#line`. public static func remark(_ message: String, file: String? = #file, line: Int? = #line) { self.emit(.remark, message, file: file, line: line) } - /// Emits a progress message + /// Emits a progress message. + /// - Parameter message: The description of the progress. public static func progress(_ message: String) { try? pluginHostConnection.sendMessage(.emitProgress(message: message)) } diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/ArgumentExtractor.md b/Sources/PackagePlugin/Documentation.docc/Curation/ArgumentExtractor.md new file mode 100644 index 00000000000..9c88d6b1b41 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/ArgumentExtractor.md @@ -0,0 +1,17 @@ +# ``PackagePlugin/ArgumentExtractor`` + +## Topics + +### Creating an Argument Extractor + +- ``init(_:)`` + +### Inspecting Arguments + +- ``remainingArguments`` +- ``unextractedOptionsOrFlags`` + +### Extracting Arguments + +- ``extractFlag(named:)`` +- ``extractOption(named:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/BinaryArtifactTarget.md b/Sources/PackagePlugin/Documentation.docc/Curation/BinaryArtifactTarget.md new file mode 100644 index 00000000000..41d43489e2e --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/BinaryArtifactTarget.md @@ -0,0 +1,19 @@ +# ``PackagePlugin/BinaryArtifactTarget`` + +## Topics + +### Inspecting the Target + +- ``id`` +- ``name`` +- ``kind-swift.property`` +- ``origin-swift.property`` +- ``artifactURL`` +- ``dependencies`` +- ``directoryURL`` +- ``Kind-swift.enum`` +- ``Origin-swift.enum`` + +- ``artifact`` +- ``directory`` + diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/BuildToolPlugin.md b/Sources/PackagePlugin/Documentation.docc/Curation/BuildToolPlugin.md new file mode 100644 index 00000000000..81fd9d9eb6f --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/BuildToolPlugin.md @@ -0,0 +1,7 @@ +# ``PackagePlugin/BuildToolPlugin`` + +## Topics + +### Creating a Build Tool Plugin + +- ``createBuildCommands(context:target:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/ClangSourceModuleTarget.md b/Sources/PackagePlugin/Documentation.docc/Curation/ClangSourceModuleTarget.md new file mode 100644 index 00000000000..6ddaf453593 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/ClangSourceModuleTarget.md @@ -0,0 +1,32 @@ +# ``PackagePlugin/ClangSourceModuleTarget`` + +## Topics + +### Inspecting a Clang Source Module Target + +- ``id`` +- ``name`` +- ``kind`` +- ``moduleName`` +- ``directoryURL`` +- ``dependencies`` +- ``headerSearchPaths`` +- ``preprocessorDefinitions`` +- ``directory`` +- ``publicHeadersDirectory`` +- ``publicHeadersDirectoryURL`` + +### Source Files + +- ``sourceFiles`` +- ``sourceFiles(withSuffix:)`` + +### Plugin Sources and Resources + +- ``pluginGeneratedSources`` +- ``pluginGeneratedResources`` + +### Linked Library and Frameworks + +- ``linkedLibraries`` +- ``linkedFrameworks`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/Command.md b/Sources/PackagePlugin/Documentation.docc/Curation/Command.md new file mode 100644 index 00000000000..15072edd7cf --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/Command.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/Command`` + +## Topics + +### Types of Build Commands + +- ``buildCommand(displayName:executable:arguments:environment:inputFiles:outputFiles:)-swift.enum.case`` +- ``prebuildCommand(displayName:executable:arguments:environment:outputFilesDirectory:)-swift.enum.case`` +- ``buildCommand(displayName:executable:arguments:environment:inputFiles:outputFiles:)-swift.type.method`` +- ``prebuildCommand(displayName:executable:arguments:environment:outputFilesDirectory:)-swift.type.method`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/CommandPlugin.md b/Sources/PackagePlugin/Documentation.docc/Curation/CommandPlugin.md new file mode 100644 index 00000000000..d0b3e4190d6 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/CommandPlugin.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/CommandPlugin`` + +## Topics + +### Creating a Command Plugin + +- ``performCommand(context:arguments:)`` + +### Accessing the Package Manager + +- ``packageManager-4z02h`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/Diagnostics.md b/Sources/PackagePlugin/Documentation.docc/Curation/Diagnostics.md new file mode 100644 index 00000000000..04382c4a506 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/Diagnostics.md @@ -0,0 +1,12 @@ +# ``PackagePlugin/Diagnostics`` + +## Topics + +### Emitting Errors and Diagnostics + +- ``progress(_:)`` +- ``error(_:file:line:)`` +- ``warning(_:file:line:)`` +- ``remark(_:file:line:)`` +- ``emit(_:_:file:line:)`` +- ``Severity`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/ExecutableProduct.md b/Sources/PackagePlugin/Documentation.docc/Curation/ExecutableProduct.md new file mode 100644 index 00000000000..0f69602f402 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/ExecutableProduct.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/ExecutableProduct`` + +## Topics + +### Inspecting an Executable Target + +- ``id`` +- ``name`` +- ``mainTarget`` +- ``targets`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/File.md b/Sources/PackagePlugin/Documentation.docc/Curation/File.md new file mode 100644 index 00000000000..fa18cbe8892 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/File.md @@ -0,0 +1,9 @@ +# ``PackagePlugin/File`` + +## Topics + +### Inspecting the File + +- ``type`` +- ``url`` +- ``path`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/FileList.md b/Sources/PackagePlugin/Documentation.docc/Curation/FileList.md new file mode 100644 index 00000000000..f8c260dc7c1 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/FileList.md @@ -0,0 +1,4 @@ +# ``PackagePlugin/FileList`` + +## Topics + diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/FileType.md b/Sources/PackagePlugin/Documentation.docc/Curation/FileType.md new file mode 100644 index 00000000000..1b8b6cf8d79 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/FileType.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/FileType`` + +## Topics + +### Types of Files + +- ``source`` +- ``header`` +- ``resource`` +- ``unknown`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/LibraryProduct.md b/Sources/PackagePlugin/Documentation.docc/Curation/LibraryProduct.md new file mode 100644 index 00000000000..d6cea0fd1be --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/LibraryProduct.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/LibraryProduct`` + +## Topics + +### Inspecting a Library Product + +- ``id`` +- ``name`` +- ``kind-swift.property`` +- ``targets`` +- ``Kind-swift.enum`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/LibraryProduct_Kind.md b/Sources/PackagePlugin/Documentation.docc/Curation/LibraryProduct_Kind.md new file mode 100644 index 00000000000..9c53d7ef1b9 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/LibraryProduct_Kind.md @@ -0,0 +1,9 @@ +# ``PackagePlugin/LibraryProduct/Kind-swift.enum`` + +## Topics + +### Kinds of Library Targets + +- ``automatic`` +- ``dynamic`` +- ``static`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/ModuleKind.md b/Sources/PackagePlugin/Documentation.docc/Curation/ModuleKind.md new file mode 100644 index 00000000000..18842f1f9aa --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/ModuleKind.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/ModuleKind`` + +## Topics + +### Kinds of Modules + +- ``executable`` +- ``test`` +- ``generic`` +- ``macro`` +- ``snippet`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/Package.md b/Sources/PackagePlugin/Documentation.docc/Curation/Package.md new file mode 100644 index 00000000000..b9422cc3d21 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/Package.md @@ -0,0 +1,27 @@ +# ``PackagePlugin/Package`` + +## Topics + +### Inspecting Packages + +- ``id`` +- ``displayName`` +- ``toolsVersion`` +- ``directoryURL`` +- ``origin`` +- ``dependencies`` +- ``sourceModules`` +- ``ID`` +- ``directory`` + +### Inspecting Package Targets + +- ``targets`` +- ``targets(named:)`` +- ``targets(ofType:)`` + +### Inspecting Package Products + +- ``products`` +- ``products(named:)`` +- ``products(ofType:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageDependency.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageDependency.md new file mode 100644 index 00000000000..902b68bd31e --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageDependency.md @@ -0,0 +1,7 @@ +# ``PackagePlugin/PackageDependency`` + +## Topics + +### Inspecting a Package Dependency + +- ``package`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager.md new file mode 100644 index 00000000000..4a2d5abf0d0 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager.md @@ -0,0 +1,25 @@ +# ``PackagePlugin/PackageManager`` + +## Topics + +### Building a Package + +- ``build(_:parameters:)`` +- ``BuildSubset`` +- ``BuildParameters`` +- ``BuildResult`` +- ``BuildConfiguration`` +- ``BuildLogVerbosity`` + +### Testing a Package + +- ``test(_:parameters:)`` +- ``TestSubset`` +- ``TestParameters`` +- ``TestResult`` + +### Retrieving Symbols for a Package + +- ``getSymbolGraph(for:options:)`` +- ``SymbolGraphOptions`` +- ``SymbolGraphResult`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManagerProxyError.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManagerProxyError.md new file mode 100644 index 00000000000..64aca79e6d7 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManagerProxyError.md @@ -0,0 +1,8 @@ +# ``PackagePlugin/PackageManagerProxyError`` + +## Topics + +### Types of Proxy Errors from Package Manager + +- ``unimplemented(_:)`` +- ``unspecified(_:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildConfiguration.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildConfiguration.md new file mode 100644 index 00000000000..d6647ead18b --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildConfiguration.md @@ -0,0 +1,13 @@ +# ``PackagePlugin/PackageManager/BuildConfiguration`` + +## Topics + +### Build Configurations + +- ``inherit`` +- ``debug`` +- ``release`` + +### Creating a Build Configuration + +- ``init(rawValue:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildLogVerbosity.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildLogVerbosity.md new file mode 100644 index 00000000000..a4572c94596 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildLogVerbosity.md @@ -0,0 +1,13 @@ +# ``PackagePlugin/PackageManager/BuildLogVerbosity`` + +## Topics + +### Verbosity Levels + +- ``concise`` +- ``debug`` +- ``verbose`` + +### Creating a Verbosity Level + +- ``init(rawValue:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildParameters.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildParameters.md new file mode 100644 index 00000000000..ed36dd3d446 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildParameters.md @@ -0,0 +1,19 @@ +# ``PackagePlugin/PackageManager/BuildParameters`` + +## Topics + +### Creating Build Parameters + +- ``init(configuration:logging:echoLogs:)`` +- ``BuildConfiguration`` +- ``BuildLogVerbosity`` + +### Inspecting Build Parameters + +- ``configuration`` +- ``logging`` +- ``echoLogs`` +- ``otherCFlags`` +- ``otherCxxFlags`` +- ``otherLinkerFlags`` +- ``otherSwiftcFlags`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildResult.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildResult.md new file mode 100644 index 00000000000..5947bdc0479 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildResult.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/PackageManager/BuildResult`` + +## Topics + +### Inspecting a Build Result + +- ``builtArtifacts`` +- ``logText`` +- ``succeeded`` +- ``BuiltArtifact`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildResult_BuiltArtifact.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildResult_BuiltArtifact.md new file mode 100644 index 00000000000..51b2dd2d073 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildResult_BuiltArtifact.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/PackageManager/BuildResult/BuiltArtifact`` + +## Topics + +### Inspecting a Build Artifact + +- ``kind-swift.property`` +- ``url`` +- ``Kind-swift.enum`` +- ``path`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildSubset.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildSubset.md new file mode 100644 index 00000000000..0c62925f79f --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_BuildSubset.md @@ -0,0 +1,9 @@ +# ``PackagePlugin/PackageManager/BuildSubset`` + +## Topics + +### Subsets of the Package + +- ``product(_:)`` +- ``target(_:)`` +- ``all(includingTests:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphOptions.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphOptions.md new file mode 100644 index 00000000000..d64ea5beda8 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphOptions.md @@ -0,0 +1,15 @@ +# ``PackagePlugin/PackageManager/SymbolGraphOptions`` + +## Topics + +### Creating Symbol Graph Options + +- ``init(minimumAccessLevel:includeSynthesized:includeSPI:emitExtensionBlocks:)`` + +### Inspecting Symbol Graph Options + +- ``emitExtensionBlocks`` +- ``includeSPI`` +- ``includeSynthesized`` +- ``minimumAccessLevel`` +- ``AccessLevel`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphOptions_AccessLevel.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphOptions_AccessLevel.md new file mode 100644 index 00000000000..fe6bf8ddbe5 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphOptions_AccessLevel.md @@ -0,0 +1,16 @@ +# ``PackagePlugin/PackageManager/SymbolGraphOptions/AccessLevel`` + +## Topics + +### Access Levels + +- ``public`` +- ``package`` +- ``open`` +- ``internal`` +- ``private`` +- ``fileprivate`` + +### Creating an Access Level + +- ``init(rawValue:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphResult.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphResult.md new file mode 100644 index 00000000000..5858fea983d --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_SymbolGraphResult.md @@ -0,0 +1,8 @@ +# ``PackagePlugin/PackageManager/SymbolGraphResult`` + +## Topics + +### Inspecting Symbol Graph Results + +- ``directoryURL`` +- ``directoryPath`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestParameters.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestParameters.md new file mode 100644 index 00000000000..2f55e966b07 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestParameters.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/PackageManager/TestParameters`` + +## Topics + +### Creating Test Parameters + +- ``init(enableCodeCoverage:)`` + +### Inspecting Test Parameters + +- ``enableCodeCoverage`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult.md new file mode 100644 index 00000000000..bcc1e5f03e9 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/PackageManager/TestResult`` + +## Topics + +### Inspecting Test Results + +- ``succeeded`` +- ``testTargets`` +- ``codeCoverageDataFileURL`` +- ``TestTarget`` +- ``codeCoverageDataFile`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget.md new file mode 100644 index 00000000000..6c73ff53b3d --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget.md @@ -0,0 +1,9 @@ +# ``PackagePlugin/PackageManager/TestResult/TestTarget`` + +## Topics + +### Inspecting a Test Target + +- ``name`` +- ``testCases`` +- ``TestCase`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase.md new file mode 100644 index 00000000000..00fa35260a6 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase.md @@ -0,0 +1,9 @@ +# ``PackagePlugin/PackageManager/TestResult/TestTarget/TestCase`` + +## Topics + +### Inspecting a Test Case + +- ``name`` +- ``tests`` +- ``Test`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase_Test.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase_Test.md new file mode 100644 index 00000000000..a5a6f5ff865 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase_Test.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/PackageManager/TestResult/TestTarget/TestCase/Test`` + +## Topics + +### Inspecting a Test in a Test Case + +- ``name`` +- ``result-swift.property`` +- ``duration`` +- ``Result-swift.enum`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase_Test_Result.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase_Test_Result.md new file mode 100644 index 00000000000..370d5f1b5c5 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestResult_TestTarget_TestCase_Test_Result.md @@ -0,0 +1,13 @@ +# ``PackagePlugin/PackageManager/TestResult/TestTarget/TestCase/Test/Result-swift.enum`` + +## Topics + +### Test Results + +- ``succeeded`` +- ``skipped`` +- ``failed`` + +### Creating a Test Result + +- ``init(rawValue:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestSubset.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestSubset.md new file mode 100644 index 00000000000..56f43300ac2 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageManager_TestSubset.md @@ -0,0 +1,8 @@ +# ``PackagePlugin/PackageManager/TestSubset`` + +## Topics + +### Subsets of Tests + +- ``all`` +- ``filtered(_:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PackageOrigin.md b/Sources/PackagePlugin/Documentation.docc/Curation/PackageOrigin.md new file mode 100644 index 00000000000..2180bd9da82 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PackageOrigin.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/PackageOrigin`` + +## Topics + +### Package Origins + +- ``repository(url:displayVersion:scmRevision:)`` +- ``registry(identity:displayVersion:)`` +- ``local(path:)`` +- ``root`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/Path.md b/Sources/PackagePlugin/Documentation.docc/Curation/Path.md new file mode 100644 index 00000000000..a60f0245c64 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/Path.md @@ -0,0 +1,8 @@ +# ``PackagePlugin/Path`` + +@Metadata { + @Available("Swift", introduced: "5.6", deprecated: "6.0") +} + +## Topics + diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PathList.md b/Sources/PackagePlugin/Documentation.docc/Curation/PathList.md new file mode 100644 index 00000000000..b8efe4722a1 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PathList.md @@ -0,0 +1,8 @@ +# ``PackagePlugin/PathList`` + +@Metadata { + @Available("Swift", introduced: "5.6", deprecated: "6.0") +} + +## Topics + diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/Plugin.md b/Sources/PackagePlugin/Documentation.docc/Curation/Plugin.md new file mode 100644 index 00000000000..7d9f888895e --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/Plugin.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/Plugin`` + +## Topics + +### Creating a plugin + +- ``init()`` + +### Invoking a plugin + +- ``main()`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PluginContext.md b/Sources/PackagePlugin/Documentation.docc/Curation/PluginContext.md new file mode 100644 index 00000000000..7cf5a2ffd08 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PluginContext.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/PluginContext`` + +## Topics + +### Inspecting the Context + +- ``pluginWorkDirectoryURL`` +- ``tool(named:)`` +- ``package`` +- ``Tool`` +- ``pluginWorkDirectory`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PluginContextError.md b/Sources/PackagePlugin/Documentation.docc/Curation/PluginContextError.md new file mode 100644 index 00000000000..0b31386e732 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PluginContextError.md @@ -0,0 +1,10 @@ +# ``PackagePlugin/PluginContextError`` + +## Topics + +### Errors from the Plugin Context + +- ``productNotFound(name:package:)`` +- ``targetNotFound(name:package:)`` +- ``toolNotFound(name:)`` +- ``toolNotSupportedOnTargetPlatform(name:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/PluginDeserializationError.md b/Sources/PackagePlugin/Documentation.docc/Curation/PluginDeserializationError.md new file mode 100644 index 00000000000..f8f95df376f --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/PluginDeserializationError.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/PluginDeserializationError`` + +## Topics + +### Errors while deserializing + +- ``missingBuildToolPluginProtocolConformance(protocolName:)`` +- ``missingCommandPluginProtocolConformance(protocolName:)`` +- ``missingXcodeProjectPluginSupport`` +- ``malformedInputJSON(_:)`` +- ``internalError(_:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/Product.md b/Sources/PackagePlugin/Documentation.docc/Curation/Product.md new file mode 100644 index 00000000000..d9d508e84c1 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/Product.md @@ -0,0 +1,11 @@ +# ``PackagePlugin/Product`` + +## Topics + +### Inspecting a Package Product + +- ``id-swift.property`` +- ``name`` +- ``sourceModules`` +- ``targets`` +- ``ID-swift.typealias`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/SourceModuleTarget.md b/Sources/PackagePlugin/Documentation.docc/Curation/SourceModuleTarget.md new file mode 100644 index 00000000000..3aa89cc7f85 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/SourceModuleTarget.md @@ -0,0 +1,14 @@ +# ``PackagePlugin/SourceModuleTarget`` + +## Topics + +### Inspecting a Source Module Target + +- ``moduleName`` +- ``kind`` +- ``linkedLibraries`` +- ``linkedFrameworks`` +- ``pluginGeneratedSources`` +- ``pluginGeneratedResources`` +- ``sourceFiles`` +- ``sourceFiles(withSuffix:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/SwiftSourceModuleTarget.md b/Sources/PackagePlugin/Documentation.docc/Curation/SwiftSourceModuleTarget.md new file mode 100644 index 00000000000..d010e790991 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/SwiftSourceModuleTarget.md @@ -0,0 +1,29 @@ +# ``PackagePlugin/SwiftSourceModuleTarget`` + +## Topics + +### Inspecting a Swift Source Module Target + +- ``id`` +- ``name`` +- ``kind`` +- ``moduleName`` +- ``directoryURL`` +- ``dependencies`` +- ``compilationConditions`` +- ``directory`` + +### Source Files + +- ``sourceFiles`` +- ``sourceFiles(withSuffix:)`` + +### Plugin Sources and Resources + +- ``pluginGeneratedSources`` +- ``pluginGeneratedResources`` + +### Linked Library and Frameworks + +- ``linkedLibraries`` +- ``linkedFrameworks`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/SystemLibraryTarget.md b/Sources/PackagePlugin/Documentation.docc/Curation/SystemLibraryTarget.md new file mode 100644 index 00000000000..c1b9b592faa --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/SystemLibraryTarget.md @@ -0,0 +1,14 @@ +# ``PackagePlugin/SystemLibraryTarget`` + +## Topics + +### Inspecting the System Library Target + +- ``id`` +- ``name`` +- ``pkgConfig`` +- ``dependencies`` +- ``compilerFlags`` +- ``linkerFlags`` +- ``directoryURL`` +- ``directory`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/Target.md b/Sources/PackagePlugin/Documentation.docc/Curation/Target.md new file mode 100644 index 00000000000..ada55a77853 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/Target.md @@ -0,0 +1,14 @@ +# ``PackagePlugin/Target`` + +## Topics + +### Inspecting a target + +- ``id-swift.property`` +- ``name`` +- ``directoryURL`` +- ``sourceModule`` +- ``dependencies`` +- ``recursiveTargetDependencies`` +- ``ID-swift.typealias`` +- ``directory`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/TargetDependency.md b/Sources/PackagePlugin/Documentation.docc/Curation/TargetDependency.md new file mode 100644 index 00000000000..77247604269 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/TargetDependency.md @@ -0,0 +1,8 @@ +# ``PackagePlugin/TargetDependency`` + +## Topics + +### Target Dependencies + +- ``product(_:)`` +- ``target(_:)`` diff --git a/Sources/PackagePlugin/Documentation.docc/Curation/ToolsVersion.md b/Sources/PackagePlugin/Documentation.docc/Curation/ToolsVersion.md new file mode 100644 index 00000000000..ac38d5f0741 --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Curation/ToolsVersion.md @@ -0,0 +1,9 @@ +# ``PackagePlugin/ToolsVersion`` + +## Topics + +### Tools Version Components + +- ``major`` +- ``minor`` +- ``patch`` diff --git a/Sources/PackagePlugin/Documentation.docc/Documentation.md b/Sources/PackagePlugin/Documentation.docc/Documentation.md new file mode 100644 index 00000000000..830cf39fc8b --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Documentation.md @@ -0,0 +1,72 @@ +# ``PackagePlugin`` + +Create plugins that extend the Swift Package Manager. + + +## Overview + +Build tool plugins generate source files as part of a build, or perform other actions at the start of every build. +The package manager invokes build tool plugins before a package is built in order to construct command invocations to run as part of the build. +Command plugins provide actions that users can perform at any time and aren't associated with a build. + +Read [Writing a build tool plugin](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/WritingBuildToolPlugin) to learn how to create build tool plugins, or [Writing a command plugin](https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/WritingCommandPlugin) to learn how to create command plugins. + +## Topics + +### Implementing Command Plugins + +- ``CommandPlugin`` +- ``PluginContext`` +- ``Plugin`` + +### Extracting Arguments + +- ``ArgumentExtractor`` + +### Implementing Build Plugins + +- ``BuildToolPlugin`` +- ``PluginContext`` +- ``Target`` +- ``Command`` + +### Interacting with Package Manager + +- ``PackageManager`` +- ``PackageManagerProxyError`` + +### Inspecting the Package Representation + +- ``Package`` +- ``ToolsVersion`` +- ``PackageOrigin`` +- ``PackageDependency`` +- ``Product`` +- ``ExecutableProduct`` +- ``LibraryProduct`` + +### Inspecting Package Targets + +- ``Target`` +- ``TargetDependency`` +- ``SourceModuleTarget`` +- ``ModuleKind`` +- ``SwiftSourceModuleTarget`` +- ``ClangSourceModuleTarget`` +- ``BinaryArtifactTarget`` +- ``SystemLibraryTarget`` + +### Inspecting Package Files + +- ``FileList`` +- ``File`` +- ``FileType`` + +- ``Path`` +- ``PathList`` + +### Plugin Diagnostics and Errors + +- ``Diagnostics`` +- ``PluginContextError`` +- ``PluginDeserializationError`` diff --git a/Sources/PackagePlugin/Documentation.docc/Info.plist b/Sources/PackagePlugin/Documentation.docc/Info.plist new file mode 100644 index 00000000000..1d479ae109f --- /dev/null +++ b/Sources/PackagePlugin/Documentation.docc/Info.plist @@ -0,0 +1,26 @@ + + + + + CFBundleName + PackagePlugin + CFBundleDisplayName + PackagePlugin + CFBundleIdentifier + org.swift.swiftpm.packageplugin + CFBundleDevelopmentRegion + en + CFBundleIconFile + DocumentationIcon + CFBundleIconName + DocumentationIcon + CFBundlePackageType + DOCS + CFBundleShortVersionString + 0.1.0 + CDDefaultCodeListingLanguage + swift + CFBundleVersion + 0.1.0 + + diff --git a/Sources/PackagePlugin/Errors.swift b/Sources/PackagePlugin/Errors.swift index 2d7a08c21f5..32352713049 100644 --- a/Sources/PackagePlugin/Errors.swift +++ b/Sources/PackagePlugin/Errors.swift @@ -10,12 +10,15 @@ // //===----------------------------------------------------------------------===// +/// Errors thrown while a plugin operates. public enum PluginContextError: Error { - /// Could not find a tool with the given name. This could be either because + /// Could not find a tool with the given name. + /// + /// This could be either because /// it doesn't exist, or because the plugin doesn't have a dependency on it. case toolNotFound(name: String) - /// Tool is not supported on the target platform + /// The tool is not supported on the target platform case toolNotSupportedOnTargetPlatform(name: String) /// Could not find a target with the given name. @@ -26,6 +29,7 @@ public enum PluginContextError: Error { } extension PluginContextError: CustomStringConvertible { + /// The string representation of the error. public var description: String { switch self { case .toolNotFound(let name): @@ -40,20 +44,24 @@ extension PluginContextError: CustomStringConvertible { } } +/// Errors thrown while loading a plugin. public enum PluginDeserializationError: Error { /// The input JSON is malformed in some way; the message provides more details. case malformedInputJSON(_ message: String) - /// The plugin doesn't support Xcode (it doesn't link against XcodeProjectPlugin). + /// The plugin doesn't support Xcode + /// + /// Typically, it doesn't link against XcodeProjectPlugin. case missingXcodeProjectPluginSupport - /// The plugin doesn't conform to an expected specialization of the BuildToolPlugin protocol. + /// The plugin doesn't conform to the BuildToolPlugin protocol. case missingBuildToolPluginProtocolConformance(protocolName: String) - /// The plugin doesn't conform to an expected specialization of the CommandPlugin protocol. + /// The plugin doesn't conform to the CommandPlugin protocol. case missingCommandPluginProtocolConformance(protocolName: String) /// An internal error of some kind; the message provides more details. case internalError(_ message: String) } extension PluginDeserializationError: CustomStringConvertible { + /// The string representation of the error. public var description: String { switch self { case .malformedInputJSON(let message): diff --git a/Sources/PackagePlugin/PackageManagerProxy.swift b/Sources/PackagePlugin/PackageManagerProxy.swift index 0119f149695..7a2cd36c9f5 100644 --- a/Sources/PackagePlugin/PackageManagerProxy.swift +++ b/Sources/PackagePlugin/PackageManagerProxy.swift @@ -13,19 +13,24 @@ import Foundation /// Provides specialized information and services from the Swift Package Manager -/// or an IDE that supports Swift Packages. Different plugin hosts implement the -/// functionality in whatever way is appropriate for them, but should preserve -/// the same semantics described here. +/// or an IDE that supports Swift packages. +/// +/// Different plugin hosts implement the functionality in whatever way is appropriate for them, +/// but are expected to preserve the semantics described by this API. public struct PackageManager { - /// Performs a build of all or a subset of products and targets in a package. + /// Performs a build of all, or a subset, of products and targets in a package. /// - /// Any errors encountered during the build are reported in the build result, - /// as is the log of the build commands that were run. This method throws an - /// error if the input parameters are invalid or in case the build cannot be + /// Return any errors encountered during the build in the build result, + /// as well as the log of the build commands that it runs. This method throws an + /// error if the input parameters are invalid, or in case the build can't be /// started. /// - /// The SwiftPM CLI or any IDE that supports packages may show the progress - /// of the build as it happens. + /// The Swift package manager command line interface or any IDE that supports + /// packages may show the progress of the build as it happens. + /// - Parameters: + /// - subset: The subset of targets to build. + /// - parameters: The build parameters to apply. + /// - Returns: The build results. public func build( _ subset: BuildSubset, parameters: BuildParameters @@ -38,10 +43,10 @@ public struct PackageManager { } } - /// Specifies a subset of products and targets of a package to build. + /// Specifies a subset of package products and targets to build. public enum BuildSubset { /// Represents the subset consisting of all products and of either all - /// targets or (if `includingTests` is false) just non-test targets. + /// targets or, if `includingTests` is false, non-test targets. case all(includingTests: Bool) /// Represents the product with the specified name. @@ -53,13 +58,15 @@ public struct PackageManager { /// Parameters and options to apply during a build. public struct BuildParameters { - /// Whether to build for debug or release. + /// The build configuration to use while building. + /// + /// Typically whether to build for debug or release. public var configuration: BuildConfiguration /// Controls the amount of detail in the log returned in the build result. public var logging: BuildLogVerbosity - /// Whether to print build logs to the console + /// A Boolean value that indicates whether to print build logs to the console. public var echoLogs: Bool /// Additional flags to pass to all C compiler invocations. @@ -74,6 +81,11 @@ public struct PackageManager { /// Additional flags to pass to all linker invocations. public var otherLinkerFlags: [String] = [] + /// Creates a new sert of build parameters. + /// - Parameters: + /// - configuration: The build configuration to use. + /// - logging: The level of detail to include in the build logs returned in the build result. + /// - echoLogs: Whether to print build logs to the console. public init( configuration: BuildConfiguration = .debug, logging: BuildLogVerbosity = .concise, @@ -85,30 +97,34 @@ public struct PackageManager { } } - /// Represents an overall purpose of the build, which affects such things - /// as optimization and generation of debug symbols. + /// The configuration to use for the build. + /// + /// The configuration affects optimization and generation of debug symbols. public enum BuildConfiguration: String { case debug, release, inherit } - /// Represents the amount of detail in a build log. + /// The amount of detail to include in a build log. public enum BuildLogVerbosity: String { case concise, verbose, debug } - /// Represents the results of running a build. + /// The results of running a build. public struct BuildResult { - /// Whether the build succeeded or failed. + /// A Boolean value that indicates whether the build succeeded or failed. public var succeeded: Bool - /// Log output (the verbatim text in the initial proposal). + /// The log output. + /// + /// The verbatim text in the initial proposal. public var logText: String - /// The artifacts built from the products in the package. Intermediates - /// such as object files produced from individual targets are not listed. + /// The artifacts built from the products in the package. + /// + /// Intermediates such as object files produced from individual targets aren't listed. public var builtArtifacts: [BuiltArtifact] - /// Represents a single artifact produced during a build. + /// The single artifact produced during a build. public struct BuiltArtifact { /// Full path of the built artifact in the local file system. @available(_PackageDescription, deprecated: 6.0, renamed: "url") @@ -116,31 +132,38 @@ public struct PackageManager { try! Path(url: self.url) } - /// Full path of the built artifact in the local file system. + /// The file URL of the built artifact in the local file system. @available(_PackageDescription, introduced: 6.0) public var url: URL - /// The kind of artifact that was built. + /// The kind of artifact built. public var kind: Kind - /// Represents the kind of artifact that was built. The specific file - /// formats may vary from platform to platform — for example, on macOS - /// a dynamic library may in fact be built as a framework. + /// The kind of artifact built. + /// + /// The specific file formats may vary from platform to platform. + /// For example, on macOS a dynamic library may in fact be built as a framework. public enum Kind: String { case executable, dynamicLibrary, staticLibrary } } } - /// Runs all or a specified subset of the unit tests of the package, after - /// an incremental build if necessary (the same as `swift test` does). - /// - /// Any test failures are reported in the test result. This method throws an - /// error if the input parameters are invalid or in case the test cannot be + /// Runs all, or a specified subset, of the unit tests of the package, after + /// an incremental build if necessary. + /// + /// The is functionally the same as `swift test` on the command line. + /// + /// The returned test result includes any test failures. This method throws an + /// error if the input parameters are invalid, or if the test cannot be /// started. - /// - /// The SwiftPM CLI or any IDE that supports packages may show the progress - /// of the tests as they happen. + /// + /// The Swift package manager command-line interface, or any IDE, + /// may show the progress of the tests as they happen. + /// - Parameters: + /// - subset: The subset of tests to run. + /// - parameters: The test parameters to apply. + /// - Returns: The test results. public func test( _ subset: TestSubset, parameters: TestParameters @@ -153,67 +176,81 @@ public struct PackageManager { } } - /// Specifies what tests in a package to run. + /// Specifies which tests to run. public enum TestSubset { - /// Represents all tests in the package. + /// All tests in the package. case all - /// Represents one or more tests filtered by regular expression, with the - /// format . or ./. + /// One or more tests filtered by regular expression. + /// Use the format `.` or + /// `./`. + /// /// This is the same as the `--filter` option of `swift test`. case filtered([String]) } - /// Parameters that control how the tests are run. + /// Parameters that control how tests are run. public struct TestParameters { - /// Whether to collect code coverage information while running the tests. + /// Whether to collect code coverage information while running tests. public var enableCodeCoverage: Bool - + + /// Creates a new set of test parameters. + /// - Parameter enableCodeCoverage: Whether to collect code coverage information while running tests. public init(enableCodeCoverage: Bool = false) { self.enableCodeCoverage = enableCodeCoverage } } - /// Represents the result of running unit tests. + /// The result of running tests. public struct TestResult { - /// Whether the test run succeeded or failed. + /// A Boolean value that indicates whether the test run succeeded. public var succeeded: Bool - /// Results for all the test targets that were run (filtered based on - /// the input subset passed when running the test). + /// Results for all the test targets run. public var testTargets: [TestTarget] - /// Path of a generated `.profdata` file suitable for processing using + /// The path of a generated profile file to provide code corage. + /// + /// The `.profdata` file is suitable for processing using /// `llvm-cov`, if `enableCodeCoverage` was set in the test parameters. @available(_PackageDescription, deprecated: 6.0, renamed: "codeCoverageDataFileURL") public var codeCoverageDataFile: Path? { self.codeCoverageDataFileURL.map { try! Path(url: $0) } } - /// Path of a generated `.profdata` file suitable for processing using + /// The file URL of a generated profile file to provide code coverage. + /// + /// The `.profdata` file is suitable for processing using /// `llvm-cov`, if `enableCodeCoverage` was set in the test parameters. @available(_PackageDescription, introduced: 6.0) public var codeCoverageDataFileURL: URL? - /// Represents the results of running some or all of the tests in a + /// The results of running some or all of the tests in a /// single test target. public struct TestTarget { + /// The name of the target. public var name: String + /// The test cases included in the target. public var testCases: [TestCase] - /// Represents the results of running some or all of the tests in + /// The results of running some or all of the tests in /// a single test case. public struct TestCase { + /// The name of the test case. public var name: String + /// The tests included in the test case. public var tests: [Test] - /// Represents the results of running a single test. + /// The results of running a single test. public struct Test { + /// The name of the test. public var name: String + /// The test result. public var result: Result + /// The duration of the test. public var duration: Double - /// Represents the result of running a single test. + /// The result of running a single test. public enum Result: String { case succeeded, skipped, failed } @@ -223,9 +260,15 @@ public struct PackageManager { } /// Return a directory containing symbol graph files for the given target - /// and options. If the symbol graphs need to be created or updated first, - /// they will be. SwiftPM or an IDE may generate these symbol graph files + /// and options. + /// + /// If the symbol graphs need to be created or updated first, they will be. + /// Swift package manager or an IDE may generate these symbol graph files /// in any way it sees fit. + /// - Parameters: + /// - target: The target to build or from which to extract symbol graphs. + /// - options: The options to use while building or extracting symbol graphs. + /// - Returns: The symbol graphs for the target you specify. public func getSymbolGraph( for target: Target, options: SymbolGraphOptions @@ -240,23 +283,31 @@ public struct PackageManager { /// Represents options for symbol graph generation. public struct SymbolGraphOptions { - /// The symbol graph will include symbols at this access level and higher. + /// The minimum access level of symbols to return. + /// + /// The symbol graph includes symbols at this access level and higher. public var minimumAccessLevel: AccessLevel - /// Represents a Swift access level. + /// The access level for a symbol. public enum AccessLevel: String, CaseIterable { case `private`, `fileprivate`, `internal`, `package`, `public`, open } - /// Whether to include synthesized members. + /// A Boolean value that indicates whether to include synthesized members. public var includeSynthesized: Bool - /// Whether to include symbols marked as SPI. + /// A Boolean value that indicates whether to include symbols marked as SPI. public var includeSPI: Bool - /// Whether to emit symbols for extensions to external types. + /// A Boolean value that indicates whether to emit symbols for extensions to external types. public var emitExtensionBlocks: Bool - + + /// Creates a new set of options for returning the symbol graph for a target. + /// - Parameters: + /// - minimumAccessLevel: The minimum access level of symbols to return. + /// - includeSynthesized: A Boolean value that indicates whether to include synthesized members. + /// - includeSPI: A Boolean value that indicates whether to include symbols marked as SPI. + /// - emitExtensionBlocks: A Boolean value that indicates whether to emit symbols for extensions to external types. public init( minimumAccessLevel: AccessLevel = .public, includeSynthesized: Bool = false, @@ -270,7 +321,7 @@ public struct PackageManager { } } - /// Represents the result of symbol graph generation. + /// The result of symbol graph generation. public struct SymbolGraphResult { /// The directory that contains the symbol graph files for the target. @available(_PackageDescription, deprecated: 6.0, renamed: "directoryURL") @@ -278,7 +329,7 @@ public struct PackageManager { try! Path(url: self.directoryURL) } - /// The directory that contains the symbol graph files for the target. + /// The file URL of the directory that contains the symbol graph files for the target. @available(_PackageDescription, introduced: 6.0) public var directoryURL: URL } @@ -305,11 +356,12 @@ extension PackageManager { } } +/// Errors from methods using the package manager. public enum PackageManagerProxyError: Error { /// Indicates that the functionality isn't implemented in the plugin host. case unimplemented(_ message: String) - /// An unspecified other kind of error from the Package Manager proxy. + /// An unspecified other kind of error from the package manager proxy. case unspecified(_ message: String) } diff --git a/Sources/PackagePlugin/PackageModel.swift b/Sources/PackagePlugin/PackageModel.swift index 397e553c60a..5712e99aa25 100644 --- a/Sources/PackagePlugin/PackageModel.swift +++ b/Sources/PackagePlugin/PackageModel.swift @@ -12,55 +12,71 @@ import Foundation -/// Represents a single package in the graph (either the root or a dependency). +/// A single package in a graph of packages. +/// +/// The package can either be the root package, or a dependency. public struct Package { - /// Unique identifier for the package. + /// The unique identifier for the package. public let id: ID + /// The type that represents a package identifier. public typealias ID = String - /// The name of the package (for display purposes only). + /// The name of the package. + /// + /// Use the name for display purposes only. public let displayName: String /// The absolute path of the package directory in the local file system. @available(_PackageDescription, deprecated: 6.0, renamed: "directoryURL") public let directory: Path - /// The absolute path of the package directory in the local file system. + /// The file URL of the package directory in the local file system. @available(_PackageDescription, introduced: 6.0) public let directoryURL: URL - /// The origin of the package (root, local, repository, registry, etc). + /// The origin of the package. public let origin: PackageOrigin /// The tools version specified by the resolved version of the package. - /// Behavior is often gated on the tools version, to make sure older + /// + /// Behavior is often gated on the tools version to make sure older /// packages continue to work as intended. public let toolsVersion: ToolsVersion - /// Any dependencies on other packages, in the same order as they are + /// Any dependencies on other packages. + /// + /// The dependencies are included in the same order as /// specified in the package manifest. public let dependencies: [PackageDependency] - /// Any regular products defined in this package (except plugin products), - /// in the same order as they are specified in the package manifest. + /// Any regular products defined in this package, with the exception of plugin products. + /// + /// The products are specified in the same order as the package manifest. public let products: [Product] - /// Any regular targets defined in this package (except plugin targets), - /// in the same order as they are specified in the package manifest. + /// Any regular targets defined in this packagewith the exception of plugin targets. + /// + /// The targets are specified in the same order as the package manifest. public let targets: [Target] } -/// Represents the origin of a package as it appears in the graph. +/// The origin of a package. public enum PackageOrigin { - /// A root package (unversioned). + /// A root package. + /// + /// The root package is unversioned. case root - /// A local package, referenced by path (unversioned). + /// A local package, referenced by path. + /// + /// A local package is unversioned. case local(path: String) /// A package from a Git repository, with a URL and with a textual /// description of the resolved version or branch name (for display - /// purposes only), along with the corresponding SCM revision. The + /// purposes only), and the corresponding SCM revision. + /// + /// The /// revision is the Git commit hash and may be useful for plugins /// that generates source code that includes version information. case repository(url: String, displayVersion: String, scmRevision: String) @@ -71,7 +87,7 @@ public enum PackageOrigin { case registry(identity: String, displayVersion: String) } -/// Represents a version of SwiftPM on whose semantics a package relies. +/// A version of Swift package manager on whose semantics a package relies. public struct ToolsVersion { /// The major version. public let major: Int @@ -89,11 +105,12 @@ public struct ToolsVersion { } } -/// Represents a resolved dependency of a package on another package. This is a -/// separate entity in order to make it easier for future versions of the API to +/// A resolved dependency of a package. +/// +/// This is a separate entity in order to make it easier for future versions of the API to /// add information about the dependency itself. public struct PackageDependency { - /// The package to which the dependency was resolved. + /// The package that is a dependency. public let package: Package init(package: Package) { @@ -101,65 +118,75 @@ public struct PackageDependency { } } -/// Represents a single product defined in a package. +/// A single product defined in a package. public protocol Product { /// Unique identifier for the product. var id: ID { get } + /// The type that represents the identifier of a package product. typealias ID = String - /// The name of the product, as defined in the package manifest. This name - /// is unique among the products of the package in which it is defined. + /// The name of the product, as defined in the package manifest. + /// + /// This name is unique among the products of the package in which it is defined. var name: String { get } /// The targets that directly comprise the product, in the order in which - /// they are declared in the package manifest. The product will contain the - /// transitive closure of the these targets and their dependencies. Some - /// kinds of products have further restrictions on the set of targets (for - /// example, an executable product must have one and only one target that - /// defines the main entry point for an executable). + /// they are declared in the package manifest. + /// + /// The product contains the transitive closure of the these targets and their + /// dependencies. Some kinds of products have further restrictions on the set of + /// targets (for example, an executable product must have one and only one + /// target that defines the main entry point for an executable). var targets: [Target] { get } } -/// Represents an executable product defined in a package. +/// An executable product defined in a package. public struct ExecutableProduct: Product { /// Unique identifier for the product. public let id: ID - /// The name of the product, as defined in the package manifest. This name - /// is unique among the products of the package in which it is defined. + /// The name of the product, as defined in the package manifest. + /// + /// This name is unique among the products of the package in which it is defined. public let name: String /// The targets that directly comprise the product, in the order in which - /// they are declared in the package manifest. The product will contain the - /// transitive closure of the these targets and their dependencies. For an - /// ExecutableProduct, exactly one of the targets in this list must be an - /// ExecutableTarget. + /// they are declared in the package manifest. + /// + /// The product contains the transitive closure of the these targets and their dependencies. + /// For an `ExecutableProduct`, exactly one of the targets in this list must be an + /// `ExecutableTarget`. public let targets: [Target] - /// The target that contains the main entry point of the executable. Every - /// executable product has exactly one main executable target. This target + /// The target that contains the main entry point of the executable. + /// + /// Every executable product has exactly one main executable target. This target /// will always be one of the targets in the product's `targets` array. public let mainTarget: Target } -/// Represents a library product defined in a package. +/// A library product defined in a package. public struct LibraryProduct: Product { /// Unique identifier for the product. public let id: ID - /// The name of the product, as defined in the package manifest. This name - /// is unique among the products of the package in which it is defined. + /// The name of the product, as defined in the package manifest. + /// + /// This name is unique among the products of the package in which + /// it is defined. public let name: String /// The targets that directly comprise the product, in the order in which - /// they are declared in the package manifest. The product will contain the - /// transitive closure of the these targets and their dependencies. + /// they are declared in the package manifest. + /// + /// The product contains the transitive closure of the these targets + /// and their dependencies. public let targets: [Target] - /// Whether the library is static, dynamic, or automatically determined. + /// A value that indicates whether the library is static, dynamic, or automatically determined. public let kind: Kind - /// Represents a kind of library product. + /// The kind of library product. public enum Kind { /// A static library, whose code is copied into its clients. case `static` @@ -173,31 +200,34 @@ public struct LibraryProduct: Product { } } -/// Represents a single target defined in a package. +/// A single target defined in a package. public protocol Target { /// Unique identifier for the target. var id: ID { get } + /// The type that represents the ID of the target. typealias ID = String - /// The name of the target, as defined in the package manifest. This name - /// is unique among the targets of the package in which it is defined. + /// The name of the target, as defined in the package manifest. + /// + /// This name is unique among the targets of the package in which it is defined. var name: String { get } /// The absolute path of the target directory in the local file system. @available(_PackageDescription, deprecated: 6.1, renamed: "directoryURL") var directory: Path { get } - /// The absolute path of the target directory in the local file system. + /// The file URL of the target directory in the local file system. @available(_PackageDescription, introduced: 6.1) var directoryURL: URL { get } /// Any other targets on which this target depends, in the same order as - /// they are specified in the package manifest. Conditional dependencies - /// that do not apply have already been filtered out. + /// they are specified in the package manifest. + /// + /// Conditional dependencies that do not apply are filtered out. var dependencies: [TargetDependency] { get } } -/// Represents a dependency of a target on a product or on another target. +/// A dependency of a target on a product or on another target. public enum TargetDependency { /// A dependency on a target in the same package. case target(Target) @@ -206,19 +236,24 @@ public enum TargetDependency { case product(Product) } -/// Represents a target consisting of a source code module, containing either -/// Swift or source files in one of the C-based languages. +/// A target consisting of a source code module. +/// +/// The module contains either Swift or source files in one of +/// the C-based languages. public protocol SourceModuleTarget: Target { - /// The name of the module produced by the target (derived from the target - /// name, though future SwiftPM versions may allow this to be customized). + /// The name of the module produced by the target. + /// + /// Derived from the target name, though future Swift package manager versions may + /// allow this to be customized. var moduleName: String { get } /// The kind of module, describing whether it contains unit tests, contains /// the main entry point of an executable, or neither. var kind: ModuleKind { get } - /// The source files that are associated with this target (any files that - /// have been excluded in the manifest have already been filtered out). + /// The source files that are associated with this target. + /// + /// Any files that have been excluded in the manifest are filtered out. var sourceFiles: FileList { get } /// Any custom linked libraries required by the module, as specified in the @@ -229,16 +264,16 @@ public protocol SourceModuleTarget: Target { /// package manifest. var linkedFrameworks: [String] { get } - /// Paths of any sources generated by other plugins that have been applied to the given target before the plugin - /// currently being executed. + /// The file URLs of any sources generated by other plugins applied to the given target before the plugin + /// being executed. /// /// Note: Plugins are applied in order of declaration in the package manifest. Generated files are vended to the /// target the current plugin is being applied to, but not necessarily to other targets in the package graph. @available(_PackageDescription, introduced: 6.0) var pluginGeneratedSources: [URL] { get } - /// Paths of any resources generated by other plugins that have been applied to the given target before the plugin - /// currently being executed. + /// The file URLs of any resources generated by other plugins that have been applied to the given target + /// before the plugin currently being executed. /// /// Note: Plugins are applied in order of declaration in the package manifest. Generated files are vended to the /// target the current plugin is being applied to, but not necessarily to other targets in the package graph. @@ -246,7 +281,7 @@ public protocol SourceModuleTarget: Target { var pluginGeneratedResources: [URL] { get } } -/// Represents the kind of module. +/// The kind of module. public enum ModuleKind { /// A module that contains generic code (not a test nor an executable). case generic @@ -262,13 +297,14 @@ public enum ModuleKind { case macro // FIXME: This should really come from `CompilerPluginSupport` somehow, but we lack the infrastructure to allow that currently. } -/// Represents a target consisting of a source code module compiled using Swift. +/// A target consisting of a source code module compiled using Swift. public struct SwiftSourceModuleTarget: SourceModuleTarget { /// Unique identifier for the target. public let id: ID - /// The name of the target, as defined in the package manifest. This name - /// is unique among the targets of the package in which it is defined. + /// The name of the target, as defined in the package manifest. + /// + /// This name is unique among the targets of the package in which it is defined. public let name: String /// The kind of module, describing whether it contains unit tests, contains @@ -279,21 +315,25 @@ public struct SwiftSourceModuleTarget: SourceModuleTarget { @available(_PackageDescription, deprecated: 6.0, renamed: "directoryURL") public let directory: Path - /// The absolute path of the target directory in the local file system. + /// The file URL of the target directory in the local file system. @available(_PackageDescription, introduced: 6.0) public let directoryURL: URL /// Any other targets on which this target depends, in the same order as - /// they are specified in the package manifest. Conditional dependencies - /// that do not apply have already been filtered out. + /// specified in the package manifest. + /// + /// Conditional dependencies that do not apply have already been filtered out. public let dependencies: [TargetDependency] - /// The name of the module produced by the target (derived from the target - /// name, though future SwiftPM versions may allow this to be customized). + /// The name of the module produced by the target. + /// + /// This is derived from the target name, though future Swift package manager + /// versions may allow this to be customized. public let moduleName: String - /// The source files that are associated with this target (any files that - /// have been excluded in the manifest have already been filtered out). + /// The source files associated with this target + /// + /// Any files that have been excluded in the manifest have already been filtered out. public let sourceFiles: FileList /// Any custom compilation conditions specified for the Swift target in the @@ -308,27 +348,30 @@ public struct SwiftSourceModuleTarget: SourceModuleTarget { /// package manifest. public let linkedFrameworks: [String] - /// Paths of any sources generated by other plugins that have been applied to the given target before the plugin - /// currently being executed. + /// The file URLs of any sources generated by other plugins that have been applied + /// to the given target before the plugin being executed. @available(_PackageDescription, introduced: 6.0) public let pluginGeneratedSources: [URL] - /// Paths of any resources generated by other plugins that have been applied to the given target before the plugin - /// currently being executed. + /// The file URLS of any resources generated by other plugins that have been applied + /// to the given target before the plugin being executed. @available(_PackageDescription, introduced: 6.0) public let pluginGeneratedResources: [URL] } -/// Represents a target consisting of a source code module compiled using Clang. +/// A target consisting of a source code module compiled using Clang. public struct ClangSourceModuleTarget: SourceModuleTarget { /// Unique identifier for the target. public let id: ID - /// The name of the target, as defined in the package manifest. This name - /// is unique among the targets of the package in which it is defined. + /// The name of the target, as defined in the package manifest. + /// + /// This name is unique among the targets of the package in which it is defined. public let name: String - /// The kind of module, describing whether it contains unit tests, contains + /// The kind of module. + /// + /// The kind of module describes whether it contains unit tests, /// the main entry point of an executable, or neither. public let kind: ModuleKind @@ -336,21 +379,25 @@ public struct ClangSourceModuleTarget: SourceModuleTarget { @available(_PackageDescription, deprecated: 6.0, renamed: "directoryURL") public let directory: Path - /// The absolute path of the target directory in the local file system. + /// The file URL of the target directory in the local file system. @available(_PackageDescription, introduced: 6.0) public let directoryURL: URL /// Any other targets on which this target depends, in the same order as - /// they are specified in the package manifest. Conditional dependencies - /// that do not apply have already been filtered out. + /// specified in the package manifest. + /// + /// Conditional dependencies that do not apply have already been filtered out. public let dependencies: [TargetDependency] - /// The name of the module produced by the target (derived from the target - /// name, though future SwiftPM versions may allow this to be customized). + /// The name of the module produced by the target. + /// + /// This is derived from the target name, though future Swift package manager + /// versions may allow this to be customized. public let moduleName: String - /// The source files that are associated with this target (any files that - /// have been excluded in the manifest have already been filtered out). + /// The source files that are associated with this target. + /// + /// Any files that have been excluded in the manifest have already been filtered out. public let sourceFiles: FileList /// Any preprocessor definitions specified for the Clang target. @@ -359,13 +406,15 @@ public struct ClangSourceModuleTarget: SourceModuleTarget { /// Any custom header search paths specified for the Clang target. public let headerSearchPaths: [String] - /// The directory containing public C headers, if applicable. This will - /// only be set for targets that have a directory of a public headers. + /// The directory containing public C headers, if applicable. + /// + /// This will only be set for targets that have a directory of a public headers. @available(_PackageDescription, deprecated: 6.0, renamed: "publicHeadersDirectoryURL") public let publicHeadersDirectory: Path? - /// The directory containing public C headers, if applicable. This will - /// only be set for targets that have a directory of a public headers. + /// The directory containing public C headers, if applicable. + /// + /// This will only be set for targets that have a directory of a public headers. @available(_PackageDescription, introduced: 6.0) public let publicHeadersDirectoryURL: URL? @@ -377,38 +426,41 @@ public struct ClangSourceModuleTarget: SourceModuleTarget { /// package manifest. public let linkedFrameworks: [String] - /// Paths of any sources generated by other plugins that have been applied to the given target before the plugin - /// currently being executed. + /// The file URLs of any sources generated by other plugins that have been applied + /// to the given target before the plugin currently being executed. @available(_PackageDescription, introduced: 6.0) public let pluginGeneratedSources: [URL] - /// Paths of any resources generated by other plugins that have been applied to the given target before the plugin - /// currently being executed. + /// The file URLs of any resources generated by other plugins that have been applied + /// to the given target before the plugin currently being executed. @available(_PackageDescription, introduced: 6.0) public let pluginGeneratedResources: [URL] } -/// Represents a target describing an artifact (e.g. a library or executable) -/// that is distributed as a binary. +/// A target describing an artifact that is distributed as a binary. +/// +/// For example, a library or executable. public struct BinaryArtifactTarget: Target { /// Unique identifier for the target. public let id: ID - /// The name of the target, as defined in the package manifest. This name - /// is unique among the targets of the package in which it is defined. + /// The name of the target, as defined in the package manifest. + /// + /// This name is unique among the targets of the package in which it is defined. public let name: String /// The absolute path of the target directory in the local file system. @available(_PackageDescription, deprecated: 6.0, renamed: "directoryURL") public let directory: Path - /// The absolute path of the target directory in the local file system. + /// The file URL of the target directory in the local file system. @available(_PackageDescription, introduced: 6.0) public let directoryURL: URL /// Any other targets on which this target depends, in the same order as - /// they are specified in the package manifest. Conditional dependencies - /// that do not apply have already been filtered out. + /// specified in the package manifest. + /// + /// Conditional dependencies that do not apply have already been filtered out. public let dependencies: [TargetDependency] /// The kind of binary artifact. @@ -417,66 +469,73 @@ public struct BinaryArtifactTarget: Target { /// The original source of the binary artifact. public let origin: Origin - /// The location of the binary artifact in the local file system. + /// The path location of the binary artifact in the local file system. @available(_PackageDescription, deprecated: 6.0, renamed: "artifactURL") public let artifact: Path - /// The location of the binary artifact in the local file system. + /// The file URL of the location of the binary artifact in the local file system. @available(_PackageDescription, introduced: 6.0) public let artifactURL: URL - /// Represents a kind of binary artifact. + /// A kind of binary artifact. public enum Kind { + /// An XCFramework. case xcframework + /// An artifact archive. case artifactsArchive } - // Represents the original location of a binary artifact. + /// The original location of a binary artifact. public enum Origin: Equatable { - /// Represents an artifact that was available locally. + /// An artifact that was available locally. case local - /// Represents an artifact that was downloaded from a remote URL. + /// An artifact that was downloaded from a remote URL. case remote(url: String) } } -/// Represents a target describing a system library that is expected to be +/// A target describing a system library that is expected to be /// present on the host system. public struct SystemLibraryTarget: Target { /// Unique identifier for the target. public let id: ID - /// The name of the target, as defined in the package manifest. This name - /// is unique among the targets of the package in which it is defined. + /// The name of the target, as defined in the package manifest. + /// + /// This name is unique among the targets of the package in which it is defined. public var name: String /// The absolute path of the target directory in the local file system. @available(_PackageDescription, deprecated: 6.0, renamed: "directoryURL") public var directory: Path - /// The absolute path of the target directory in the local file system. + /// The file URL of the target directory in the local file system. @available(_PackageDescription, introduced: 6.0) public var directoryURL: URL /// Any other targets on which this target depends, in the same order as - /// they are specified in the package manifest. Conditional dependencies - /// that do not apply have already been filtered out. + /// specified in the package manifest. + /// + /// Conditional dependencies that do not apply have already been filtered out. public var dependencies: [TargetDependency] /// The name of the `pkg-config` file, if any, describing the library. public let pkgConfig: String? - /// Flags from `pkg-config` to pass to Clang (and to SwiftC via `-Xcc`). + /// Flags from `pkg-config` to pass to Clang and SwiftC. + /// + /// Flags are passed to using `-Xcc`. public let compilerFlags: [String] /// Flags from `pkg-config` to pass to the platform linker. public let linkerFlags: [String] } -/// Provides information about a list of files. The order is not defined -/// but is guaranteed to be stable. This allows the implementation to be -/// more efficient than a static file list. +/// Provides information about a list of files. +/// +/// The order is not defined but is guaranteed to be stable. +/// This allows the implementation to be more efficient than a static file list. public struct FileList { private var files: [File] @@ -512,7 +571,7 @@ extension FileList: RandomAccessCollection { public subscript(i: Int) -> File { self.files[i] } } -/// Provides information about a single file in a FileList. +/// Information about a single file in a FileList. public struct File { /// The path of the file. @available(_PackageDescription, deprecated: 6.0, renamed: "url") @@ -520,11 +579,11 @@ public struct File { return try! Path(url: url) } - /// The path of the file. + /// The URL of the file. @available(_PackageDescription, introduced: 6.0) public let url: URL - /// File type, as determined by SwiftPM. + /// The File type, as determined by Swift package manager. public let type: FileType @_spi(PackagePluginInternal) public init(url: URL, type: FileType) { @@ -533,9 +592,10 @@ public struct File { } } -/// Provides information about the type of a file. Any future cases will -/// use availability annotations to make sure existing plugins still work -/// until they increase their required tools version. +/// Information about the type of a file. +/// +/// Future cases will use availability annotations to make sure existing plugins +/// continue to work until they increase their required tools version. public enum FileType { /// A source file. case source @@ -543,16 +603,19 @@ public enum FileType { /// A header file. case header - /// A resource file (either processed or copied). + /// A resource file. + /// + /// A resource file may be either processed or copied. case resource /// A file not covered by any other rule. case unknown } -/// Provides information about a list of paths. The order is not defined -/// but is guaranteed to be stable. This allows the implementation to be -/// more efficient than a static path list. +/// Provides information about a list of paths. +/// +/// The order is not defined but is guaranteed to be stable. +/// This allows the implementation to be more efficient than a static path list. public struct PathList { private var paths: [URL] diff --git a/Sources/PackagePlugin/Plugin.swift b/Sources/PackagePlugin/Plugin.swift index 5589c23462e..22cf928bfe9 100644 --- a/Sources/PackagePlugin/Plugin.swift +++ b/Sources/PackagePlugin/Plugin.swift @@ -79,8 +79,9 @@ import Android extension Plugin { - /// Main entry point of the plugin — sets up a communication channel with - /// the plugin host and runs the main message loop. + /// The main entry point of the plugin. + /// + /// This sets up a communication channel with the plugin host and runs the main message loop. public static func main() async throws { // Duplicate the `stdin` file descriptor, which we will then use for // receiving messages from the plugin host. diff --git a/Sources/PackagePlugin/Protocols.swift b/Sources/PackagePlugin/Protocols.swift index 3e3fd35fb05..e4a2471abc1 100644 --- a/Sources/PackagePlugin/Protocols.swift +++ b/Sources/PackagePlugin/Protocols.swift @@ -10,43 +10,49 @@ // //===----------------------------------------------------------------------===// -/// Defines functionality common to all SwiftPM plugins, such as the way to -/// instantiate the plugin. +// A future improvement to the package manager would be to allow use of +// a plugin to also provide configuration parameters for that plugin. +// Any proposal that adds such a facility should also add initializers +// to set those values as plugin properties. + +/// A protocol that defines functionality common to all package manger plugins. /// -/// A future improvement to SwiftPM would be to allow usage of a plugin to -/// also provide configuration parameters for that plugin. A proposal that -/// adds such a facility should also add initializers to set those values -/// as plugin properties. +/// For example, the way to instantiate and run a plugin. public protocol Plugin { - /// Instantiates the plugin. This happens once per invocation of the - /// plugin; there is no facility for keeping in-memory state from one - /// invocation to the next. Most plugins do not need to implement the - /// initializer. + + + /// Instantiates the plugin. + /// + /// This happens once per invocation of the plugin. + /// There is no facility for keeping in-memory state from one invocation to the next. + /// Most plugins do not need to implement the initializer. init() } -/// Defines functionality for all plugins having a `buildTool` capability. +/// The plugin protocol that defines functionality for all plugins having a buildTool capability. public protocol BuildToolPlugin: Plugin { - /// Invoked by SwiftPM to create build commands for a particular target. + /// Invoked by the package manager to create build commands for a particular target. + /// /// The context parameter contains information about the package and its /// dependencies, as well as other environmental inputs. /// /// This function should create and return build commands or prebuild /// commands, configured based on the information in the context. Note - /// that it does not directly run those commands. + /// that the plugin does not directly run those commands. func createBuildCommands( context: PluginContext, target: Target ) async throws -> [Command] } -/// Defines functionality for all plugins that have a `command` capability. +/// The plugin protocol that defines functionality for all plugins that have a command capability. public protocol CommandPlugin: Plugin { - /// Invoked by SwiftPM to perform the custom actions of the command. + /// Invoked by the package manager to perform the custom actions of the command. func performCommand( - /// The context in which the plugin is invoked. This is the same for all - /// kinds of plugins, and provides access to the package graph, to cache - /// directories, etc. + /// The context in which the plugin is invoked. + /// + /// This is the same for all kinds of plugins, and provides access to the package graph, + /// to cache directories, and so on. context: PluginContext, /// Any literal arguments passed after the verb in the command invocation. diff --git a/Sources/PackagePlugin/Utilities.swift b/Sources/PackagePlugin/Utilities.swift index d84382d8139..bba632c5ed7 100644 --- a/Sources/PackagePlugin/Utilities.swift +++ b/Sources/PackagePlugin/Utilities.swift @@ -13,8 +13,9 @@ import Foundation extension Package { - /// The list of targets matching the given names. Throws an error if any of - /// the targets cannot be found. + /// The list of targets matching the given names. + /// + /// Throws an error if any of the targets cannot be found. public func targets(named targetNames: [String]) throws -> [Target] { return try targetNames.map { name in guard let target = self.targets.first(where: { $0.name == name }) else { @@ -24,8 +25,9 @@ extension Package { } } - /// The list of products matching the given names. Throws an error if any of - /// the products cannot be found. + /// The list of products matching the given names. + /// + /// Throws an error if any of the products cannot be found. public func products(named productNames: [String]) throws -> [Product] { return try productNames.map { name in guard let product = self.products.first(where: { $0.name == name }) else { @@ -49,9 +51,12 @@ extension Product { } extension Target { - /// The transitive closure of all the targets on which the receiver depends, - /// ordered such that every dependency appears before any other target that - /// depends on it (i.e. in "topological sort order"). + /// The transitive closure of all the targets on which the receiver depends. + /// + /// Package manager orders the results such that every dependency appears before any other target that + /// depends on it. + /// + /// The dependencies are sorted in topological sort order. public var recursiveTargetDependencies: [Target] { // FIXME: We can rewrite this to use a stack instead of recursion. var visited = Set() @@ -70,7 +75,7 @@ extension Target { return self.dependencies.flatMap{ dependencyClosure(for: $0) } } - /// Convenience accessor which casts the receiver to`SourceModuleTarget` if possible. + /// Convenience accessor which casts the receiver to`SourceModuleTarget`, if possible. @available(_PackageDescription, introduced: 5.9) public var sourceModule: SourceModuleTarget? { return self as? SourceModuleTarget