[PackageModel] Add a new target kind - provided library

This target points to a prebuilt library that comes from
a certain location in a toolchain. It's going to be injected
by the package manager into library manifests and shouldn't
be accessible via user-facing APIs.

Author: xedin

Sources/Build/BuildDescription/ProductBuildDescription.swift

@@ -45,6 +45,9 @@ package final class ProductBuildDescription: SPMBuildCore.ProductBuildDescriptio
     // Computed during build planning.
     var dylibs: [ProductBuildDescription] = []
 
+    /// The list of provided libraries that are going to be used by this product.
+    var providedLibraries: [String: AbsolutePath] = [:]
+
     /// Any additional flags to be added. These flags are expected to be computed during build planning.
     var additionalFlags: [String] = []
 
@@ -156,6 +159,8 @@ package final class ProductBuildDescription: SPMBuildCore.ProductBuildDescriptio
             args += ["-F", self.buildParameters.buildPath.pathString]
         }
 
+        self.providedLibraries.forEach { args += ["-L", $1.pathString, "-l", $0] }
+
         args += ["-L", self.buildParameters.buildPath.pathString]
         args += try ["-o", binaryPath.pathString]
         args += ["-module-name", self.product.name.spm_mangledToC99ExtendedIdentifier()]

Sources/Build/BuildManifest/LLBuildManifestBuilder+Swift.swift

@@ -424,6 +424,8 @@ extension LLBuildManifestBuilder {
             if target.underlying is BinaryTarget { return }
             // Ignore Plugin Targets.
             if target.underlying is PluginTarget { return }
+            // Ignore Provided Libraries.
+            if target.underlying is ProvidedLibraryTarget { return }
 
             // Depend on the binary for executable targets.
             if target.type == .executable {

Sources/Build/BuildPlan/BuildPlan+Product.swift

@@ -115,6 +115,8 @@ extension BuildPlan {
         }
         buildProduct.libraryBinaryPaths = dependencies.libraryBinaryPaths
 
+        buildProduct.providedLibraries = dependencies.providedLibraries
+
         buildProduct.availableTools = dependencies.availableTools
     }
 
@@ -127,6 +129,7 @@ extension BuildPlan {
         staticTargets: [ResolvedModule],
         systemModules: [ResolvedModule],
         libraryBinaryPaths: Set<AbsolutePath>,
+        providedLibraries: [String: AbsolutePath],
         availableTools: [String: AbsolutePath]
     ) {
         /* Prior to tools-version 5.9, we used to erroneously recursively traverse executable/plugin dependencies and statically include their
@@ -204,6 +207,7 @@ extension BuildPlan {
         var staticTargets = [ResolvedModule]()
         var systemModules = [ResolvedModule]()
         var libraryBinaryPaths: Set<AbsolutePath> = []
+        var providedLibraries = [String: AbsolutePath]()
         var availableTools = [String: AbsolutePath]()
 
         for dependency in allTargets {
@@ -257,6 +261,8 @@ extension BuildPlan {
                     }
                 case .plugin:
                     continue
+                case .providedLibrary:
+                    providedLibraries[target.name] = target.underlying.path
                 }
 
             case .product(let product, _):
@@ -274,7 +280,7 @@ extension BuildPlan {
             }
         }
 
-        return (linkLibraries, staticTargets, systemModules, libraryBinaryPaths, availableTools)
+        return (linkLibraries, staticTargets, systemModules, libraryBinaryPaths, providedLibraries, availableTools)
     }
 
     /// Extracts the artifacts  from an artifactsArchive

Sources/Build/BuildPlan/BuildPlan+Swift.swift

@@ -14,6 +14,7 @@ import struct Basics.InternalError
 import class PackageModel.BinaryTarget
 import class PackageModel.ClangTarget
 import class PackageModel.SystemLibraryTarget
+import class PackageModel.ProvidedLibraryTarget
 
 extension BuildPlan {
     func plan(swiftTarget: SwiftTargetBuildDescription) throws {
@@ -48,6 +49,10 @@ extension BuildPlan {
                         swiftTarget.libraryBinaryPaths.insert(library.libraryPath)
                     }
                 }
+            case let target as ProvidedLibraryTarget:
+                swiftTarget.additionalFlags += [
+                    "-I", target.path.pathString
+                ]
             default:
                 break
             }

Sources/Build/BuildPlan/BuildPlan.swift

@@ -433,7 +433,7 @@ public class BuildPlan: SPMBuildCore.BuildPlan {
                     toolsVersion: toolsVersion,
                     fileSystem: fileSystem
                 ))
-            case is SystemLibraryTarget, is BinaryTarget:
+            case is SystemLibraryTarget, is BinaryTarget, is ProvidedLibraryTarget:
                 break
             default:
                 throw InternalError("unhandled \(target.underlying)")

Sources/Commands/Snippets/Cards/TopCard.swift

@@ -153,6 +153,8 @@ fileprivate extension Target.Kind {
             return "snippets"
         case .macro:
             return "macros"
+        case .providedLibrary:
+            return "provided libraries"
         }
     }
 }

Sources/PackageLoading/PackageBuilder.swift

@@ -542,6 +542,16 @@ public final class PackageBuilder {
                     throw ModuleError.artifactNotFound(targetName: target.name, expectedArtifactName: target.name)
                 }
                 return artifact.path
+            } else if let targetPath = target.path, target.type == .providedLibrary {
+                guard let path = try? AbsolutePath(validating: targetPath) else {
+                    throw ModuleError.invalidCustomPath(target: target.name, path: targetPath)
+                }
+
+                if !self.fileSystem.isDirectory(path) {
+                    throw ModuleError.unsupportedTargetPath(targetPath)
+                }
+
+                return path
             } else if let subpath = target.path { // If there is a custom path defined, use that.
                 if subpath == "" || subpath == "." {
                     return self.packagePath
@@ -855,6 +865,11 @@ public final class PackageBuilder {
                 path: potentialModule.path,
                 origin: artifactOrigin
             )
+        } else if potentialModule.type == .providedLibrary {
+            return ProvidedLibraryTarget(
+                name: potentialModule.name,
+                path: potentialModule.path
+            )
         }
 
         // Check for duplicate target dependencies

Sources/PackageModel/CMakeLists.txt

@@ -51,6 +51,7 @@ add_library(PackageModel
   Target/BinaryTarget.swift
   Target/ClangTarget.swift
   Target/PluginTarget.swift
+  Target/ProvidedLibraryTarget.swift
   Target/SwiftTarget.swift
   Target/SystemLibraryTarget.swift
   Target/Target.swift

Sources/PackageModel/Manifest/TargetDescription.swift

@@ -21,6 +21,7 @@ public struct TargetDescription: Hashable, Encodable, Sendable {
         case binary
         case plugin
         case `macro`
+        case providedLibrary
     }
 
     /// Represents a target's dependency on another entity.
@@ -222,6 +223,19 @@ public struct TargetDescription: Hashable, Encodable, Sendable {
             if pkgConfig != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "pkgConfig") }
             if providers != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "providers") }
             if pluginCapability != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "pluginCapability") }
+        case .providedLibrary:
+            if path == nil { throw Error.providedLibraryTargetRequiresPath(targetName: name) }
+            if url != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "url") }
+            if !dependencies.isEmpty { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "dependencies") }
+            if !exclude.isEmpty { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "exclude") }
+            if sources != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "sources") }
+            if !resources.isEmpty { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "resources") }
+            if publicHeadersPath != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "publicHeadersPath") }
+            if pkgConfig != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "pkgConfig") }
+            if providers != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "providers") }
+            if pluginCapability != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "pluginCapability") }
+            if !settings.isEmpty { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "settings") }
+            if pluginUsages != nil { throw Error.disallowedPropertyInTarget(targetName: name, propertyName: "pluginUsages") }
         }
 
         self.name = name
@@ -370,13 +384,16 @@ import protocol Foundation.LocalizedError
 private enum Error: LocalizedError, Equatable {
     case binaryTargetRequiresEitherPathOrURL(targetName: String)
     case disallowedPropertyInTarget(targetName: String, propertyName: String)
-    
+    case providedLibraryTargetRequiresPath(targetName: String)
+
     var errorDescription: String? {
         switch self {
         case .binaryTargetRequiresEitherPathOrURL(let targetName):
             return "binary target '\(targetName)' neither defines neither path nor URL for its artifacts"
         case .disallowedPropertyInTarget(let targetName, let propertyName):
             return "target '\(targetName)' contains a value for disallowed property '\(propertyName)'"
+        case .providedLibraryTargetRequiresPath(let targetName):
+            return "provided library target '\(targetName)' does not define a path to the library"
         }
     }
 }

Sources/PackageModel/ManifestSourceGeneration.swift

@@ -317,6 +317,8 @@ fileprivate extension SourceCodeFragment {
             self.init(enum: "plugin", subnodes: params, multiline: true)
         case .macro:
             self.init(enum: "macro", subnodes: params, multiline: true)
+        case .providedLibrary:
+            self.init(enum: "providedLibrary", subnodes: params, multiline: true)
         }
     }