Getting Started with Swift SDKs for WebAssembly

WebAssembly (Wasm) is a virtual instruction set focused on portability, security, and performance. Developers can build client and server applications for Wasm and then deploy them in the browser or other Wasm runtime implementations.

WebAssembly support in Swift started out as a community project. Any instruction set benefits tremendously from a standardized ABI and system interfaces, and from its inception Wasm support in Swift targeted WebAssembly System Interface, which made porting Swift core libraries to this platform much easier.

Starting with Swift 6.2 and development snapshots you can easily cross-compile and run Wasm modules with Swift SDKs for Wasm distributed on swift.org. The distributed artifact bundles also include support for the experimental Embedded Swift mode.

Installation

Note that these steps are required on macOS even if you already have latest Xcode installed. Cross-compilation with Swift SDKs on Windows hosts is not supported yet.

  1. Install swiftly per the instructions for the platform that you’re bulding on.

  2. Install Swift 6.2 with swiftly install 6.2.

  3. Select the installed toolchain with swiftly use 6.2.

  4. Run a command in your terminal application to install Swift SDKs for Wasm.
     swift sdk install https://download.swift.org/swift-6.2-release/wasm/swift-6.2-RELEASE/swift-6.2-RELEASE_wasm.artifactbundle.tar.gz --checksum fe4e8648309fce86ea522e9e0d1dc48e82df6ba6e5743dbf0c53db8429fb5224
    
  5. Run swift sdk list to verify the Swift SDK was installed and note its ID in the output. Two Swift SDKs will be installed, one with support for all Swift features, and the other with a subset of features allowed in the experimental Embedded Swift mode.

    Swift SDK ID Description
    swift-<version>_wasm Supports all Swift features
    swift-<version>_wasm-embedded Supports a subset of features allowed in the experimental Embedded Swift mode
  6. In the future, after installing or selecting a new version of the toolchain with swiftly make sure to install and use an exactly matching Swift SDK version.

Building and Running

Let’s create a simple package to see the Swift SDK in action:

mkdir Hello
cd Hello
swift package init --type executable

Modify freshly created Sources/Hello/Hello.swift file to print different strings depending on the target platform:

@main
struct wasi_test {
    static func main() {
#if os(WASI)
        print("Hello from WASI!")
#else
        print("Hello from the host system!")
#endif
    }
}

Build your package with the following command, substituting the ID from step 5 of the “Installation” section above.

swift build --swift-sdk swift-6.2-RELEASE_wasm

Recent toolchain snapshots that are compatible with Swift SDKs for Wasm also include WasmKit, which is a Wasm runtime that swift run can delegate to for execution. To run the freshly built module, use swift run with the same --swift-sdk option:

swift run --swift-sdk swift-6.2-RELEASE_wasm

You should see the following output:

[1/1] Planning build
Building for debugging...
[8/8] Linking Hello.wasm
Build of product 'Hello' complete! (1.31s)
Hello from WASI!

Embedded Swift Support

Embedded Swift is an experimental subset of the language allowing the toolchain to produce Wasm binaries that are multiple orders of magnitude smaller. One of the Swift SDKs in the artifact bundle you’ve installed with the swift sdk install command is tailored specifically for Embedded Swift.

To build with Embedded Swift SDK, pass its ID as noted in swift sdk list output (which has an -embedded suffix) in the --swift-sdk option. For example:

swift build --swift-sdk swift-6.2-RELEASE_wasm-embedded

or

swift run --swift-sdk swift-6.2-RELEASE_wasm-embedded