Update Swift SDK nomenclature (#6678)

Introduced `SwiftSDKMetadataV4` type that uses `targetTriple` instead of `runTimeTriple`. We're keeping the previous v3 schema for better error handling in case v3 schema ended up being used in the wild during Swift 5.9 development cycle. The plan is to deprecate v3 and earlier schemas in a future change.

`buildTimeTriple` and `runTimeTriple` renamed to `hostTriple` and `targetTriple` across the codebase, destinations renamed to Swift SDKs where possible without a broader disruption. Full renaming of the `Destination` type to `SwiftSDK` would come in a separate change to reduce the diff for this one.

Author: MaxDesiatov

Sources/CoreCommands/SwiftTool.swift

@@ -736,7 +736,7 @@ public final class SwiftTool {
                 {
                     destination = matchingDestination
                 } else {
-                    return .failure(DestinationError.noDestinationsDecoded(customDestination))
+                    return .failure(SwiftSDKError.noSwiftSDKDecoded(customDestination))
                 }
             } else if let triple = options.build.customCompileTriple,
                       let targetDestination = Destination.defaultDestination(for: triple, host: hostDestination)

Sources/PackageModel/Destination.swift

@@ -18,8 +18,8 @@ import enum TSCBasic.ProcessEnv
 
 import struct TSCUtility.Version
 
-/// Errors related to cross-compilation destinations.
-public enum DestinationError: Swift.Error {
+/// Errors related to Swift SDKs.
+public enum SwiftSDKError: Swift.Error {
     /// A passed argument is neither a valid file system path nor a URL.
     case invalidPathOrURL(String)
 
@@ -32,67 +32,67 @@ public enum DestinationError: Swift.Error {
     /// Name of the destination bundle is not valid.
     case invalidBundleName(String)
 
-    /// No valid destinations were decoded from a destination file.
-    case noDestinationsDecoded(AbsolutePath)
+    /// No valid Swift SDKs were decoded from a metadata file.
+    case noSwiftSDKDecoded(AbsolutePath)
 
     /// Path used for storing destination configuration data is not a directory.
     case pathIsNotDirectory(AbsolutePath)
 
-    /// A destination couldn't be serialized with the latest serialization schema, potentially because it
+    /// Swift SDK metadata couldn't be serialized with the latest serialization schema, potentially because it
     /// was deserialized from an earlier incompatible schema version or initialized manually with properties
     /// required for initialization missing.
-    case unserializableDestination
+    case unserializableMetadata
 
-    /// No configuration values are available for this destination and run-time triple.
-    case destinationNotFound(artifactID: String, builtTimeTriple: Triple, runTimeTriple: Triple)
+    /// No configuration values are available for this Swift SDK and target triple.
+    case swiftSDKNotFound(artifactID: String, hostTriple: Triple, targetTriple: Triple)
 
-    /// A destination bundle with this name is already installed, can't install a new bundle with the same name.
-    case destinationBundleAlreadyInstalled(bundleName: String)
+    /// A Swift SDK bundle with this name is already installed, can't install a new bundle with the same name.
+    case swiftSDKBundleAlreadyInstalled(bundleName: String)
 
-    /// A destination with this artifact ID is already installed. Can't install a new bundle with this artifact,
+    /// A Swift SDK with this artifact ID is already installed. Can't install a new bundle with this artifact,
     /// installed artifact IDs are expected to be unique.
-    case destinationArtifactAlreadyInstalled(installedBundleName: String, newBundleName: String, artifactID: String)
+    case swiftSDKArtifactAlreadyInstalled(installedBundleName: String, newBundleName: String, artifactID: String)
 
     #if os(macOS)
     /// Quarantine attribute should be removed by the `xattr` command from an installed bundle.
     case quarantineAttributePresent(bundlePath: AbsolutePath)
     #endif
 }
 
-extension DestinationError: CustomStringConvertible {
+extension SwiftSDKError: CustomStringConvertible {
     public var description: String {
         switch self {
         case .invalidPathOrURL(let argument):
             return "`\(argument)` is neither a valid filesystem path nor a URL."
         case .invalidSchemaVersion:
-            return "unsupported destination file schema version"
+            return "unsupported Swift SDK file schema version"
         case .invalidInstallation(let problem):
             return problem
         case .invalidBundleName(let name):
             return """
             invalid bundle name `\(name)`, unpacked Swift SDK bundles are expected to have `.artifactbundle` extension
             """
-        case .noDestinationsDecoded(let path):
-            return "no valid Swift SDKs were decoded from a destination file at path `\(path)`"
+        case .noSwiftSDKDecoded(let path):
+            return "no valid Swift SDKs were decoded from a metadata file at path `\(path)`"
         case .pathIsNotDirectory(let path):
             return "path expected to be a directory is not a directory or doesn't exist: `\(path)`"
-        case .unserializableDestination:
+        case .unserializableMetadata:
             return """
             Swift SDK configuration couldn't be serialized with the latest serialization schema, potentially because \
             it was deserialized from an earlier incompatible schema version or initialized manually with missing \
             properties required for initialization
             """
-        case .destinationNotFound(let artifactID, let buildTimeTriple, let runTimeTriple):
+        case .swiftSDKNotFound(let artifactID, let hostTriple, let targetTriple):
             return """
-            Swift SDK with ID `\(artifactID)`, build-time triple \(buildTimeTriple), and run-time triple \
-            \(runTimeTriple) is not currently installed.
+            Swift SDK with ID `\(artifactID)`, host triple \(hostTriple), and target triple \(targetTriple) is not \
+            currently installed.
             """
-        case .destinationBundleAlreadyInstalled(let bundleName):
+        case .swiftSDKBundleAlreadyInstalled(let bundleName):
             return """
             Swift SDK bundle with name `\(bundleName)` is already installed. Can't install a new bundle \
             with the same name.
             """
-        case .destinationArtifactAlreadyInstalled(let installedBundleName, let newBundleName, let artifactID):
+        case .swiftSDKArtifactAlreadyInstalled(let installedBundleName, let newBundleName, let artifactID):
             return """
             A Swift SDK with artifact ID `\(artifactID)` is already included in an installed bundle with name \
             `\(installedBundleName)`. Can't install a new bundle `\(newBundleName)` with this artifact, artifact IDs \
@@ -242,7 +242,10 @@ public struct Destination: Equatable {
         /// - Parameters:
         ///   - properties: properties of the destination for the given triple.
         ///   - destinationDirectory: directory used for converting relative paths in `properties` to absolute paths.
-        init(_ properties: SerializedDestinationV3.TripleProperties, destinationDirectory: AbsolutePath? = nil) throws {
+        fileprivate init(
+            _ properties: SerializedDestinationV3.TripleProperties,
+            destinationDirectory: AbsolutePath? = nil
+        ) throws {
             if let destinationDirectory {
                 self.init(
                     sdkRootPath: try AbsolutePath(validating: properties.sdkRootPath, relativeTo: destinationDirectory),
@@ -284,6 +287,52 @@ public struct Destination: Equatable {
             }
         }
 
+        /// Initialize paths configuration from values deserialized using v4 schema.
+        /// - Parameters:
+        ///   - properties: properties of a Swift SDK for the given triple.
+        ///   - swiftSDKDirectory: directory used for converting relative paths in `properties` to absolute paths.
+        fileprivate init(_ properties: SwiftSDKMetadataV4.TripleProperties, swiftSDKDirectory: AbsolutePath? = nil) throws {
+            if let swiftSDKDirectory {
+                self.init(
+                    sdkRootPath: try AbsolutePath(validating: properties.sdkRootPath, relativeTo: swiftSDKDirectory),
+                    swiftResourcesPath: try properties.swiftResourcesPath.map {
+                        try AbsolutePath(validating: $0, relativeTo: swiftSDKDirectory)
+                    },
+                    swiftStaticResourcesPath: try properties.swiftStaticResourcesPath.map {
+                        try AbsolutePath(validating: $0, relativeTo: swiftSDKDirectory)
+                    },
+                    includeSearchPaths: try properties.includeSearchPaths?.map {
+                        try AbsolutePath(validating: $0, relativeTo: swiftSDKDirectory)
+                    },
+                    librarySearchPaths: try properties.librarySearchPaths?.map {
+                        try AbsolutePath(validating: $0, relativeTo: swiftSDKDirectory)
+                    },
+                    toolsetPaths: try properties.toolsetPaths?.map {
+                        try AbsolutePath(validating: $0, relativeTo: swiftSDKDirectory)
+                    }
+                )
+            } else {
+                self.init(
+                    sdkRootPath: try AbsolutePath(validating: properties.sdkRootPath),
+                    swiftResourcesPath: try properties.swiftResourcesPath.map {
+                        try AbsolutePath(validating: $0)
+                    },
+                    swiftStaticResourcesPath: try properties.swiftStaticResourcesPath.map {
+                        try AbsolutePath(validating: $0)
+                    },
+                    includeSearchPaths: try properties.includeSearchPaths?.map {
+                        try AbsolutePath(validating: $0)
+                    },
+                    librarySearchPaths: try properties.librarySearchPaths?.map {
+                        try AbsolutePath(validating: $0)
+                    },
+                    toolsetPaths: try properties.toolsetPaths?.map {
+                        try AbsolutePath(validating: $0)
+                    }
+                )
+            }
+        }
+
         public mutating func merge(with newConfiguration: Self) {
             if let sdkRootPath = newConfiguration.sdkRootPath {
                 self.sdkRootPath = sdkRootPath
@@ -410,7 +459,7 @@ public struct Destination: Equatable {
                 environment: environment
             ).spm_chomp()
             guard !sdkPathStr.isEmpty else {
-                throw DestinationError.invalidInstallation("default SDK not found")
+                throw SwiftSDKError.invalidInstallation("default SDK not found")
             }
             sdkPath = try AbsolutePath(validating: sdkPathStr)
         }
@@ -571,12 +620,56 @@ extension Destination {
                     destinationDirectory: destinationDirectory
                 )
             }
+
+        case Version(4, 0, 0):
+            let swiftSDKs = try decoder.decode(path: path, fileSystem: fileSystem, as: SwiftSDKMetadataV4.self)
+            let swiftSDKDirectory = path.parentDirectory
+
+            return try swiftSDKs.targetTriples.map { triple, properties in
+                let triple = try Triple(triple)
+
+                let pathStrings = properties.toolsetPaths ?? []
+                let toolset = try pathStrings.reduce(into: Toolset(knownTools: [:], rootPaths: [])) {
+                    try $0.merge(
+                        with: Toolset(
+                            from: .init(validating: $1, relativeTo: swiftSDKDirectory),
+                            at: fileSystem,
+                            observabilityScope
+                        )
+                    )
+                }
+
+                return try Destination(
+                    targetTriple: triple,
+                    properties: properties,
+                    toolset: toolset,
+                    swiftSDKDirectory: swiftSDKDirectory
+                )
+            }
         default:
-            throw DestinationError.invalidSchemaVersion
+            throw SwiftSDKError.invalidSchemaVersion
         }
     }
 
-    
+    /// Initialize new Swift SDK from values deserialized using v4 schema.
+    /// - Parameters:
+    ///   - targetTriple: triple of the machine running code built with this Swift SDK.
+    ///   - properties: properties of the Swift SDK for the given triple.
+    ///   - toolset: combined toolset used by this Swift SDK.
+    ///   - swiftSDKDirectory: directory used for converting relative paths in `properties` to absolute paths.
+    init(
+        targetTriple: Triple,
+        properties: SwiftSDKMetadataV4.TripleProperties,
+        toolset: Toolset = .init(),
+        swiftSDKDirectory: AbsolutePath? = nil
+    ) throws {
+        self.init(
+            targetTriple: targetTriple,
+            toolset: toolset,
+            pathsConfiguration: try .init(properties, swiftSDKDirectory: swiftSDKDirectory)
+        )
+    }
+
     /// Initialize new destination from values deserialized using v3 schema.
     /// - Parameters:
     ///   - runTimeTriple: triple of the machine running code built with this destination.
@@ -643,7 +736,7 @@ extension Destination {
                 )
             )
         default:
-            throw DestinationError.invalidSchemaVersion
+            throw SwiftSDKError.invalidSchemaVersion
         }
     }
 
@@ -653,12 +746,12 @@ extension Destination {
     /// from different schema versions or constructed manually without providing valid values for such properties.
     var serialized: (Triple, SerializedDestinationV3.TripleProperties) {
         get throws {
-            guard let runTimeTriple = self.targetTriple, let sdkRootDir = self.pathsConfiguration.sdkRootPath else {
-                throw DestinationError.unserializableDestination
+            guard let targetTriple = self.targetTriple, let sdkRootDir = self.pathsConfiguration.sdkRootPath else {
+                throw SwiftSDKError.unserializableMetadata
             }
 
             return (
-                runTimeTriple,
+                targetTriple,
                 .init(
                     sdkRootPath: sdkRootDir.pathString,
                     swiftResourcesPath: self.pathsConfiguration.swiftResourcesPath?.pathString,
@@ -748,3 +841,29 @@ struct SerializedDestinationV3: Decodable {
     /// Mapping of triple strings to corresponding properties of such run-time triple.
     let runTimeTriples: [String: TripleProperties]
 }
+
+/// Represents v4 schema of `swift-sdk.json` (previously `destination.json`) files used for cross-compilation.
+struct SwiftSDKMetadataV4: Decodable {
+    struct TripleProperties: Codable {
+        /// Path relative to `swift-sdk.json` containing SDK root.
+        var sdkRootPath: String
+
+        /// Path relative to `swift-sdk.json` containing Swift resources for dynamic linking.
+        var swiftResourcesPath: String?
+
+        /// Path relative to `swift-sdk.json` containing Swift resources for static linking.
+        var swiftStaticResourcesPath: String?
+
+        /// Array of paths relative to `swift-sdk.json` containing headers.
+        var includeSearchPaths: [String]?
+
+        /// Array of paths relative to `swift-sdk.json` containing libraries.
+        var librarySearchPaths: [String]?
+
+        /// Array of paths relative to `swift-sdk.json` containing toolset files.
+        var toolsetPaths: [String]?
+    }
+
+    /// Mapping of triple strings to corresponding properties of such target triple.
+    let targetTriples: [String: TripleProperties]
+}

Sources/PackageModel/SwiftSDKBundle.swift

@@ -171,7 +171,7 @@ public struct SwiftSDKBundle {
             {
                 bundlePath = originalBundlePath
             } else {
-                throw DestinationError.invalidPathOrURL(bundlePathOrURL)
+                throw SwiftSDKError.invalidPathOrURL(bundlePathOrURL)
             }
 
             try await installIfValid(
@@ -205,16 +205,16 @@ public struct SwiftSDKBundle {
         let regex = try RegEx(pattern: "(.+\\.artifactbundle).*")
 
         guard let bundleName = bundlePath.components.last else {
-            throw DestinationError.invalidPathOrURL(bundlePath.pathString)
+            throw SwiftSDKError.invalidPathOrURL(bundlePath.pathString)
         }
 
         guard let unpackedBundleName = regex.matchGroups(in: bundleName).first?.first else {
-            throw DestinationError.invalidBundleName(bundleName)
+            throw SwiftSDKError.invalidBundleName(bundleName)
         }
 
         let installedBundlePath = destinationsDirectory.appending(component: unpackedBundleName)
         guard !fileSystem.exists(installedBundlePath) else {
-            throw DestinationError.destinationBundleAlreadyInstalled(bundleName: unpackedBundleName)
+            throw SwiftSDKError.swiftSDKBundleAlreadyInstalled(bundleName: unpackedBundleName)
         }
 
         // If there's no archive extension on the bundle name, assuming it's not archived and returning the same path.
@@ -246,7 +246,7 @@ public struct SwiftSDKBundle {
         #if os(macOS)
         // Check the quarantine attribute on bundles downloaded manually in the browser.
         guard !fileSystem.hasAttribute(.quarantine, bundlePath) else {
-            throw DestinationError.quarantineAttributePresent(bundlePath: bundlePath)
+            throw SwiftSDKError.quarantineAttributePresent(bundlePath: bundlePath)
         }
         #endif
 
@@ -262,7 +262,7 @@ public struct SwiftSDKBundle {
             fileSystem.isDirectory(unpackedBundlePath),
             let bundleName = unpackedBundlePath.components.last
         else {
-            throw DestinationError.pathIsNotDirectory(bundlePath)
+            throw SwiftSDKError.pathIsNotDirectory(bundlePath)
         }
 
         let installedBundlePath = destinationsDirectory.appending(component: bundleName)
@@ -283,7 +283,7 @@ public struct SwiftSDKBundle {
         for installedBundle in installedBundles {
             for artifactID in installedBundle.artifacts.keys {
                 guard !newArtifactIDs.contains(artifactID) else {
-                    throw DestinationError.destinationArtifactAlreadyInstalled(
+                    throw SwiftSDKError.swiftSDKArtifactAlreadyInstalled(
                         installedBundleName: installedBundle.name,
                         newBundleName: validatedBundle.name,
                         artifactID: artifactID
@@ -296,12 +296,12 @@ public struct SwiftSDKBundle {
     }
 
     /// Parses metadata of an `.artifactbundle` and validates it as a bundle containing
-    /// cross-compilation destinations.
+    /// cross-compilation Swift SDKs.
     /// - Parameters:
     ///   - bundlePath: path to the bundle root directory.
     ///   - fileSystem: filesystem containing the bundle.
     ///   - observabilityScope: observability scope to log validation warnings.
-    /// - Returns: Validated `DestinationsBundle` containing validated `Destination` values for
+    /// - Returns: Validated `SwiftSDKBundle` containing validated `Destination` values for
     /// each artifact and its variants.
     private static func parseAndValidate(
         bundlePath: AbsolutePath,
@@ -313,7 +313,7 @@ public struct SwiftSDKBundle {
             rootPath: bundlePath
         )
 
-        return try parsedManifest.validateDestinationBundle(
+        return try parsedManifest.validateSwiftSDKBundle(
             bundlePath: bundlePath,
             fileSystem: fileSystem,
             observabilityScope: observabilityScope
@@ -322,7 +322,7 @@ public struct SwiftSDKBundle {
 }
 
 extension ArtifactsArchiveMetadata {
-    fileprivate func validateDestinationBundle(
+    fileprivate func validateSwiftSDKBundle(
         bundlePath: AbsolutePath,
         fileSystem: FileSystem,
         observabilityScope: ObservabilityScope