Add WebAssembly platform to Swift build system based on Swift SDK (swiftlang#51)

* Add WebAssembly platform to Swift build system based on Swift SDK

This change adds a new platform, `webassembly`, to the Swift build system.
The platform is based on the existing Swift SDK artifact bundles, which
can be installed by SwiftPM.
To build your Xcode project for WebAssembly, you need to install a Swift
SDK for WebAssembly and Swift OSS toolchain that supports WebAssembly
compilation target, then set the `SDKROOT`, `SUPPORTED_PLATFORMS` and
`TOOLCHAINS` macros in your Xcode project file like below:

```
SDKROOT = DEVELOPMENT-SNAPSHOT-2025-01-11-a-wasm32-unknown-wasip1-threads
SUPPORTED_PLATFORMS = webassembly
TOOLCHAINS = org.swift.62202501101a
```

* Move `SwiftSDK` type to shared `SWBCore` module

* Remove deployment target concept from WebAssembly platform

The deployment target concept is not applicable to WebAssembly, as it
does not have platform versions like other platforms.

* Add a issue link to the linker flags hack

* Gate the rpath trick for Swift-in-the-OS platforms only

* Add test case for C/C++-based WASI target

* Define Wasm-specific xcspecs and remove several workarounds

* Comment about a future direction for generalizing the plugin

* Update Package.swift to adopt Swift 6 mode for Wasm platform targets

Author: kateinoigakukun

Package.swift

@@ -208,6 +208,10 @@ let package = Package(
             name: "SWBUniversalPlatform",
             dependencies: ["SWBCore"],
             swiftSettings: swiftSettings(languageMode: .v6)),
+        .target(
+            name: "SWBWebAssemblyPlatform",
+            dependencies: ["SWBCore"],
+            swiftSettings: swiftSettings(languageMode: .v6)),
         .target(
             name: "SWBWindowsPlatform",
             dependencies: ["SWBCore"],
@@ -256,6 +260,10 @@ let package = Package(
             name: "SWBUniversalPlatformTests",
             dependencies: ["SWBUniversalPlatform", "SWBTestSupport"],
             swiftSettings: swiftSettings(languageMode: .v6)),
+        .testTarget(
+            name: "SWBWebAssemblyPlatformTests",
+            dependencies: ["SWBWebAssemblyPlatform", "SWBTestSupport"],
+            swiftSettings: swiftSettings(languageMode: .v6)),
         .testTarget(
             name: "SWBWindowsPlatformTests",
             dependencies: ["SWBWindowsPlatform", "SWBTestSupport"],
@@ -371,6 +379,7 @@ let pluginTargetNames = [
     "SWBGenericUnixPlatform",
     "SWBQNXPlatform",
     "SWBUniversalPlatform",
+    "SWBWebAssemblyPlatform",
     "SWBWindowsPlatform",
 ]
 

Sources/SWBBuildService/BuildServiceEntryPoint.swift

@@ -32,6 +32,7 @@ private import SWBApplePlatform
 private import SWBGenericUnixPlatform
 private import SWBQNXPlatform
 private import SWBUniversalPlatform
+private import SWBWebAssemblyPlatform
 private import SWBWindowsPlatform
 #endif
 
@@ -128,6 +129,7 @@ extension BuildService {
             SWBGenericUnixPlatform.initializePlugin(pluginManager)
             SWBQNXPlatform.initializePlugin(pluginManager)
             SWBUniversalPlatform.initializePlugin(pluginManager)
+            SWBWebAssemblyPlatform.initializePlugin(pluginManager)
             SWBWindowsPlatform.initializePlugin(pluginManager)
             #else
             // Otherwise, load the normal plugins.

Sources/SWBCore/Specs/Tools/LinkerTools.swift

@@ -291,9 +291,10 @@ public final class LdLinkerSpec : GenericLinkerSpec, SpecIdentifierType {
         // NOTE: For swift.org toolchains, we always add the search paths to the Swift SDK location as the overlays do not have the install name set. This also works when `SWIFT_USE_DEVELOPMENT_TOOLCHAIN_RUNTIME=YES` as `DYLD_LIBRARY_PATH` is used to override these settings during debug time. If users wish to use the development runtime while not debugging, they need to manually set their rpaths as this is not a supported configuration.
         // Also, if the deployment target does not support Swift in the OS, the rpath entries need to be added as well.
         // And, if the deployment target does not support Swift Concurrency natively, then the rpath needs to be added as well so that the shim library can find the real implementation. Note that we assume `true` in the case where `supportsSwiftInTheOS` is `nil` as we don't have the platform data to make the correct choice; so fallback to existing behavior.
+        // The all above discussion is only relevant for platforms that support Swift in the OS.
         let supportsSwiftConcurrencyNatively = cbc.producer.platform?.supportsSwiftConcurrencyNatively(cbc.scope, forceNextMajorVersion: false, considerTargetDeviceOSVersion: false) ?? true
         let shouldEmitRPathForSwiftConcurrency = UserDefaults.allowRuntimeSearchPathAdditionForSwiftConcurrency && !supportsSwiftConcurrencyNatively
-        if (cbc.producer.platform?.supportsSwiftInTheOS(cbc.scope, forceNextMajorVersion: true, considerTargetDeviceOSVersion: false) != true || cbc.producer.toolchains.usesSwiftOpenSourceToolchain || shouldEmitRPathForSwiftConcurrency) && isUsingSwift {
+        if (cbc.producer.platform?.supportsSwiftInTheOS(cbc.scope, forceNextMajorVersion: true, considerTargetDeviceOSVersion: false) != true || cbc.producer.toolchains.usesSwiftOpenSourceToolchain || shouldEmitRPathForSwiftConcurrency) && isUsingSwift && cbc.producer.platform?.minimumOSForSwiftInTheOS != nil {
                 // NOTE: For swift.org toolchains, this is fine as `DYLD_LIBRARY_PATH` is used to override these settings.
             let swiftABIVersion =  await (cbc.producer.swiftCompilerSpec.discoveredCommandLineToolSpecInfo(cbc.producer, cbc.scope, delegate) as? DiscoveredSwiftCompilerToolSpecInfo)?.swiftABIVersion
                 runpathSearchPaths.insert( swiftABIVersion.flatMap { "/usr/lib/swift-\($0)" } ?? "/usr/lib/swift", at: 0)

Sources/SWBCore/SwiftSDK.swift

@@ -0,0 +1,151 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+public import SWBUtil
+import Foundation
+
+/// Represents a Swift SDK
+///
+/// See https://github.com/swiftlang/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md
+public struct SwiftSDK: Sendable {
+    struct SchemaVersionInfo: Codable {
+        let schemaVersion: String
+    }
+
+    public struct TripleProperties: Codable, Sendable {
+        public var sdkRootPath: String
+        public var swiftResourcesPath: String?
+        public var swiftStaticResourcesPath: String?
+        public var includeSearchPaths: [String]?
+        public var librarySearchPaths: [String]?
+        public var toolsetPaths: [String]?
+    }
+    struct MetadataV4: Codable {
+        let targetTriples: [String: TripleProperties]
+    }
+
+    struct Toolset: Codable {
+        struct ToolProperties: Codable {
+            var path: String?
+            var extraCLIOptions: [String]
+        }
+
+        var knownTools: [String: ToolProperties] = [:]
+        var rootPaths: [String] = []
+    }
+
+    /// The identifier of the artifact bundle containing this SDK.
+    public let identifier: String
+    /// The version of the artifact bundle containing this SDK.
+    public let version: String
+    /// The path to the SDK.
+    public let path: Path
+    /// Target-specific properties for this SDK.
+    public let targetTriples: [String: TripleProperties]
+
+    init?(identifier: String, version: String, path: Path, fs: any FSProxy) throws {
+        self.identifier = identifier
+        self.version = version
+        self.path = path
+
+        let metadataPath = path.join("swift-sdk.json")
+        guard fs.exists(metadataPath) else { return nil }
+
+        let metadataData = try Data(fs.read(metadataPath))
+        let schema = try JSONDecoder().decode(SchemaVersionInfo.self, from: metadataData)
+        guard schema.schemaVersion == "4.0" else { return nil }
+
+        let metadata = try JSONDecoder().decode(MetadataV4.self, from: metadataData)
+        self.targetTriples = metadata.targetTriples
+    }
+
+    /// The default location storing Swift SDKs installed by SwiftPM.
+    static var defaultSwiftSDKsDirectory: Path {
+        get throws {
+            try FileManager.default.url(
+                for: .libraryDirectory,
+                in: .userDomainMask,
+                appropriateFor: nil,
+                create: false
+            ).appendingPathComponent("org.swift.swiftpm").appendingPathComponent("swift-sdks").filePath
+        }
+    }
+
+    /// Find Swift SDKs installed by SwiftPM.
+    public static func findSDKs(targetTriples: [String], fs: any FSProxy) throws -> [SwiftSDK] {
+        return try findSDKs(swiftSDKsDirectory: defaultSwiftSDKsDirectory, targetTriples: targetTriples, fs: fs)
+    }
+
+    private static func findSDKs(swiftSDKsDirectory: Path, targetTriples: [String], fs: any FSProxy) throws -> [SwiftSDK] {
+        var sdks: [SwiftSDK] = []
+        // Find .artifactbundle in the SDK directory (e.g. ~/Library/org.swift.swiftpm/swift-sdks)
+        for artifactBundle in try fs.listdir(swiftSDKsDirectory) {
+            guard artifactBundle.hasSuffix(".artifactbundle") else { continue }
+            let artifactBundlePath = swiftSDKsDirectory.join(artifactBundle)
+            guard fs.isDirectory(artifactBundlePath) else { continue }
+
+            sdks.append(contentsOf: (try? findSDKs(artifactBundle: artifactBundlePath, targetTriples: targetTriples, fs: fs)) ?? [])
+        }
+        return sdks
+    }
+
+    private struct BundleInfo: Codable {
+        let artifacts: [String: Artifact]
+
+        struct Artifact: Codable {
+            let type: String
+            let version: String
+            let variants: [Variant]
+        }
+
+        struct Variant: Codable {
+            let path: String
+            let supportedTriples: [String]?
+        }
+    }
+
+    /// Find Swift SDKs in an artifact bundle supporting one of the given targets.
+    private static func findSDKs(artifactBundle: Path, targetTriples: [String], fs: any FSProxy) throws -> [SwiftSDK] {
+        // Load info.json from the artifact bundle
+        let infoPath = artifactBundle.join("info.json")
+        guard try fs.isFile(infoPath) else { return [] }
+        
+        let infoData = try Data(fs.read(infoPath))
+
+        let schema = try JSONDecoder().decode(SchemaVersionInfo.self, from: infoData)
+        guard schema.schemaVersion == "1.0" else {
+            // Ignore unknown artifact bundle format
+            return []
+        }
+
+        let info = try JSONDecoder().decode(BundleInfo.self, from: infoData)
+
+        var sdks: [SwiftSDK] = []
+
+        for (identifier, artifact) in info.artifacts {
+            for variant in artifact.variants {
+                let sdkPath = artifactBundle.join(variant.path)
+                guard fs.isDirectory(sdkPath) else { continue }
+
+                // FIXME: For now, we only support SDKs that are compatible with any host triple.
+                guard variant.supportedTriples?.isEmpty ?? true else { continue }
+
+                guard let sdk = try SwiftSDK(identifier: identifier, version: artifact.version, path: sdkPath, fs: fs) else { continue }
+                // Filter out SDKs that don't support any of the target triples.
+                guard targetTriples.contains(where: { sdk.targetTriples[$0] != nil }) else { continue }
+                sdks.append(sdk)
+            }
+        }
+
+        return sdks
+    }
+}

Sources/SWBTestSupport/CoreTestSupport.swift

@@ -21,6 +21,7 @@ private import SWBApplePlatform
 private import SWBGenericUnixPlatform
 private import SWBQNXPlatform
 private import SWBUniversalPlatform
+private import SWBWebAssemblyPlatform
 private import SWBWindowsPlatform
 #endif
 
@@ -96,6 +97,9 @@ extension Core {
             if !skipLoadingPluginsNamed.contains("com.apple.dt.SWBUniversalPlatformPlugin") {
                 SWBUniversalPlatform.initializePlugin(pluginManager)
             }
+            if !skipLoadingPluginsNamed.contains("com.apple.dt.SWBWebAssemblyPlatformPlugin") {
+                SWBWebAssemblyPlatform.initializePlugin(pluginManager)
+            }
             if !skipLoadingPluginsNamed.contains("com.apple.dt.SWBWindowsPlatformPlugin") {
                 SWBWindowsPlatform.initializePlugin(pluginManager)
             }

Sources/SWBTestSupport/RunDestinationTestSupport.swift

@@ -268,6 +268,11 @@ extension _RunDestinationInfo {
     package static var qnx: Self {
         return .init(platform: "qnx", sdk: "qnx", sdkVariant: "qnx", targetArchitecture: "undefined_arch", supportedArchitectures: ["aarch64", "x86_64"], disableOnlyActiveArch: true)
     }
+
+    /// A run destination targeting WebAssembly/WASI generic device, using the public SDK.
+    package static var wasm: Self {
+        return .init(platform: "webassembly", sdk: "webassembly", sdkVariant: "webassembly", targetArchitecture: "wasm32", supportedArchitectures: ["wasm32"], disableOnlyActiveArch: true)
+    }
 }
 
 extension RunDestinationInfo {

Sources/SWBTestSupport/SkippedTestSupport.swift

@@ -70,6 +70,7 @@ extension KnownSDK {
     package static let linux: Self = "linux"
     package static let android: Self = "android"
     package static let qnx: Self = "qnx"
+    package static let wasi: Self = "wasi"
 }
 
 package final class ConditionTraitContext: CoreBasedTests, Sendable {

Sources/SWBWebAssemblyPlatform/Plugin.swift

@@ -0,0 +1,132 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift open source project
+//
+// Copyright (c) 2025 Apple Inc. and the Swift project authors
+// Licensed under Apache License v2.0 with Runtime Library Exception
+//
+// See http://swift.org/LICENSE.txt for license information
+// See http://swift.org/CONTRIBUTORS.txt for the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+public import SWBUtil
+import SWBCore
+import SWBMacro
+import Foundation
+
+@PluginExtensionSystemActor public func initializePlugin(_ manager: PluginManager) {
+    manager.register(WebAssemblyPlatformSpecsExtension(), type: SpecificationsExtensionPoint.self)
+    manager.register(WebAssemblyPlatformExtension(), type: PlatformInfoExtensionPoint.self)
+    manager.register(WebAssemblySDKRegistryExtension(), type: SDKRegistryExtensionPoint.self)
+}
+
+struct WebAssemblyPlatformSpecsExtension: SpecificationsExtension {
+    func specificationFiles() -> Bundle? {
+        .module
+    }
+}
+
+struct WebAssemblyPlatformExtension: PlatformInfoExtension {
+    func additionalPlatforms() -> [(path: Path, data: [String: PropertyListItem])] {
+        [
+            (.root, [
+                "Type": .plString("Platform"),
+                "Name": .plString("webassembly"),
+                "Identifier": .plString("webassembly"),
+                "Description": .plString("webassembly"),
+                "FamilyName": .plString("WebAssembly"),
+                "FamilyIdentifier": .plString("webassembly"),
+                "IsDeploymentPlatform": .plString("YES"),
+            ])
+        ]
+    }
+}
+
+// TODO: We currently hardcode WebAssembly-specific information here but
+// ideally we should be able to generalize this to any Swift SDK. Some of
+// issues including https://github.com/swiftlang/swift-build/issues/3 prevent
+// us from doing this today but we should revisit this later and consider
+// renaming this plugin to something like `SWBSwiftSDKPlatform`.
+struct WebAssemblySDKRegistryExtension: SDKRegistryExtension {
+    func additionalSDKs(platformRegistry: PlatformRegistry) async -> [(path: Path, platform: SWBCore.Platform?, data: [String: PropertyListItem])] {
+        guard let host = try? ProcessInfo.processInfo.hostOperatingSystem() else {
+            return []
+        }
+
+        guard let wasmPlatform = platformRegistry.lookup(name: "webassembly") else {
+            return []
+        }
+
+        let defaultProperties: [String: PropertyListItem] = [
+            "SDK_STAT_CACHE_ENABLE": "NO",
+
+            // Workaround to avoid `-add_ast_path` on WebAssembly, apparently this needs to perform some "swift modulewrap" step instead.
+            "GCC_GENERATE_DEBUGGING_SYMBOLS": .plString("NO"),
+
+            "GENERATE_TEXT_BASED_STUBS": "NO",
+            "GENERATE_INTERMEDIATE_TEXT_BASED_STUBS": "NO",
+
+            "CHOWN": "/usr/bin/chown",
+
+            "LIBTOOL": .plString(host.imageFormat.executableName(basename: "llvm-lib")),
+            "AR": .plString(host.imageFormat.executableName(basename: "llvm-ar")),
+        ]
+
+        // Map triple to parsed triple components
+        let supportedTriples: [String: (arch: String, os: String, env: String?)] = [
+            "wasm32-unknown-wasi": ("wasm32", "wasi", nil),
+            "wasm32-unknown-wasip1": ("wasm32", "wasip1", nil),
+            "wasm32-unknown-wasip1-threads": ("wasm32", "wasip1", "threads"),
+        ]
+
+        let wasmSwiftSDKs = (try? SwiftSDK.findSDKs(
+            targetTriples: Array(supportedTriples.keys),
+            fs: localFS
+        )) ?? []
+
+        var wasmSDKs: [(path: Path, platform: SWBCore.Platform?, data: [String: PropertyListItem])] = []
+
+        for wasmSDK in wasmSwiftSDKs {
+            for (triple, tripleProperties) in wasmSDK.targetTriples {
+                guard let (arch, os, env) = supportedTriples[triple] else {
+                    continue
+                }
+
+                let wasiSysroot = wasmSDK.path.join(tripleProperties.sdkRootPath)
+                let swiftResourceDir = wasmSDK.path.join(tripleProperties.swiftResourcesPath)
+
+                wasmSDKs.append((wasiSysroot, wasmPlatform, [
+                    "Type": .plString("SDK"),
+                    "Version": .plString("1.0.0"),
+                    "CanonicalName": .plString(wasmSDK.identifier),
+                    "IsBaseSDK": .plBool(true),
+                    "DefaultProperties": .plDict([
+                        "PLATFORM_NAME": .plString("webassembly"),
+                    ].merging(defaultProperties, uniquingKeysWith: { _, new in new })),
+                    "CustomProperties": .plDict([
+                        "LLVM_TARGET_TRIPLE_OS_VERSION": .plString(os),
+                        "SWIFT_LIBRARY_PATH": .plString(swiftResourceDir.join("wasi").str),
+                        "SWIFT_RESOURCE_DIR": .plString(swiftResourceDir.str),
+                        // HACK: Ld step does not use swiftc as linker driver but instead uses clang, so we need to add some Swift specific flags
+                        // assuming static linking.
+                        // Tracked in https://github.com/swiftlang/swift-build/issues/3
+                        "OTHER_LDFLAGS": .plArray(["-lc++", "-lc++abi", "-resource-dir", "$(SWIFT_RESOURCE_DIR)/clang", "@$(SWIFT_LIBRARY_PATH)/static-executable-args.lnk"]),
+                    ]),
+                    "SupportedTargets": .plDict([
+                        "webassembly": .plDict([
+                            "Archs": .plArray([.plString(arch)]),
+                            "LLVMTargetTripleEnvironment": .plString(env ?? ""),
+                            "LLVMTargetTripleSys": .plString(os),
+                            "LLVMTargetTripleVendor": .plString("unknown"),
+                        ])
+                    ]),
+                    // TODO: Leave compatible toolchain information in Swift SDKs
+                    // "Toolchains": .plArray([])
+                ]))
+            }
+        }
+
+        return wasmSDKs
+    }
+}