Add new providedLibrary package reference kind

This kind of reference is going to be returned by package
resolution if it detects that a provided library version
matches all of the constraints.

This makes it easier to handle provided libraries post-resolution
instead of eliding them completely.

Author: xedin

Sources/Build/BuildPlan/BuildPlan.swift

@@ -740,7 +740,7 @@ extension ResolvedPackage {
         switch self.underlying.manifest.packageKind {
         case .registry, .remoteSourceControl, .localSourceControl:
             return true
-        case .root, .fileSystem:
+        case .root, .fileSystem, .providedLibrary:
             return false
         }
     }

Sources/PackageGraph/ModulesGraph.swift

@@ -358,7 +358,8 @@ extension PackageGraphError: CustomStringConvertible {
                 switch $0.manifest.packageKind {
                 case .root(let path),
                         .fileSystem(let path),
-                        .localSourceControl(let path):
+                        .localSourceControl(let path),
+                        .providedLibrary(let path):
                     description += " (at '\(path)')"
                 case .remoteSourceControl(let url):
                     description += " (from '\(url)')"

Sources/PackageGraph/Resolution/PubGrub/PubGrubDependencyResolver.swift

@@ -897,7 +897,7 @@ extension PackageRequirement {
 extension PackageReference {
     public func matchingPrebuiltLibrary(in availableLibraries: [LibraryMetadata]) -> LibraryMetadata? {
         switch self.kind {
-        case .fileSystem, .localSourceControl, .root:
+        case .fileSystem, .localSourceControl, .root, .providedLibrary:
             return nil // can never match a prebuilt library
         case .registry(let identity):
             if let registryIdentity = identity.registry {

Sources/PackageLoading/ManifestJSONParser.swift

@@ -83,7 +83,7 @@ enum ManifestJSONParser {
         case .localSourceControl(let _packagePath):
             // we have a more accurate path than the virtual one
             packagePath = _packagePath
-        case .root(let _packagePath), .fileSystem(let _packagePath):
+        case .root(let _packagePath), .fileSystem(let _packagePath), .providedLibrary(let _packagePath):
             // we dont have a more accurate path, and they should be the same
             // asserting (debug only) to make sure refactoring is correct 11/2023
             assert(packagePath == _packagePath, "expecting package path '\(packagePath)' to be the same as '\(_packagePath)'")

Sources/PackageModel/IdentityResolver.swift

@@ -46,6 +46,8 @@ public struct DefaultIdentityResolver: IdentityResolver {
             return try self.resolveIdentity(for: url)
         case .registry(let identity):
             return identity
+        case .providedLibrary(let path):
+            return try self.resolveIdentity(for: path)
         }
     }
 

Sources/PackageModel/PackageReference.swift

@@ -34,6 +34,9 @@ public struct PackageReference {
         /// A package from  a registry.
         case registry(PackageIdentity)
 
+        /// A prebuilt library provided by a toolchain
+        case providedLibrary(AbsolutePath)
+
         // FIXME: we should not need this once we migrate off URLs
         //@available(*, deprecated)
         public var locationString: String {
@@ -49,6 +52,8 @@ public struct PackageReference {
             case .registry(let identity):
                 // FIXME: this is a placeholder
                 return identity.description
+            case .providedLibrary(let path):
+                return path.pathString
             }
         }
 
@@ -70,6 +75,8 @@ public struct PackageReference {
                 return "remoteSourceControl \(url)"
             case .registry(let identity):
                 return "registry \(identity)"
+            case .providedLibrary(let path):
+                return "library \(path)"
             }
         }
 
@@ -124,6 +131,8 @@ public struct PackageReference {
         case .registry(let identity):
             // FIXME: this is a placeholder
             self.deprecatedName = name ?? identity.description
+        case .providedLibrary(let path):
+            self.deprecatedName = name ?? PackageIdentityParser.computeDefaultName(fromPath: path)
         }
     }
 
@@ -151,6 +160,10 @@ public struct PackageReference {
     public static func registry(identity: PackageIdentity) -> PackageReference {
         PackageReference(identity: identity, kind: .registry(identity))
     }
+
+    public static func library(identity: PackageIdentity, path: AbsolutePath) -> PackageReference {
+        PackageReference(identity: identity, kind: .providedLibrary(path))
+    }
 }
 
 extension PackageReference: Equatable {
@@ -203,7 +216,7 @@ extension PackageReference: CustomStringConvertible {
 
 extension PackageReference.Kind: Encodable {
     private enum CodingKeys: String, CodingKey {
-        case root, fileSystem, localSourceControl, remoteSourceControl, registry
+        case root, fileSystem, localSourceControl, remoteSourceControl, registry, providedLibrary
     }
 
     public func encode(to encoder: Encoder) throws {
@@ -224,6 +237,9 @@ extension PackageReference.Kind: Encodable {
         case .registry:
             var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .registry)
             try unkeyedContainer.encode(self.isRoot)
+        case .providedLibrary(let path):
+            var unkeyedContainer = container.nestedUnkeyedContainer(forKey: .providedLibrary)
+            try unkeyedContainer.encode(path)
         }
     }
 }

Sources/SPMBuildCore/Plugins/PluginContextSerializer.swift

@@ -240,6 +240,8 @@ internal struct PluginContextSerializer {
                 return .repository(url: url.absoluteString, displayVersion: String(describing: package.manifest.version), scmRevision: String(describing: package.manifest.revision))
             case .registry(let identity):
                 return .registry(identity: identity.description, displayVersion: String(describing: package.manifest.version))
+            case .providedLibrary(_):
+                throw InternalError("provided libraries are not supported in plugin context")
             }
         }
 

Sources/SPMTestSupport/MockManifestLoader.swift

@@ -109,6 +109,9 @@ extension ManifestLoader {
             packageIdentity = identity
             // FIXME: placeholder
             packageLocation = identity.description
+        case .providedLibrary(let path):
+            packageIdentity = try identityResolver.resolveIdentity(for: path)
+            packageLocation = path.pathString
         }
         return try await self.load(
             manifestPath: manifestPath,
@@ -156,6 +159,9 @@ extension ManifestLoader {
             packageIdentity = identity
             // FIXME: placeholder
             packageLocation = identity.description
+        case .providedLibrary(let path):
+            packageIdentity = try identityResolver.resolveIdentity(for: path)
+            packageLocation = path.pathString
         }
         return try await self.load(
             packagePath: packagePath,

Sources/SPMTestSupport/MockWorkspace.swift

@@ -1041,6 +1041,8 @@ extension PackageReference.Kind {
             return "remoteSourceControl"
         case .registry:
             return "registry"
+        case .providedLibrary:
+            return "library"
         }
     }
 }

Sources/Workspace/CMakeLists.txt

@@ -15,6 +15,7 @@ add_library(Workspace
   ManagedArtifact.swift
   ManagedDependency.swift
   PackageContainer/FileSystemPackageContainer.swift
+  PackageContainer/ProvidedLibraryPackageContainer.swift
   PackageContainer/RegistryPackageContainer.swift
   PackageContainer/SourceControlPackageContainer.swift
   ResolvedFileWatcher.swift