swift-mirror/docs/WebAssembly.md

WebAssembly support in Swift

WebAssembly is a platform that significantly differs from hardware platforms that Swift already supports. While it's a virtual machine, there are considerations to be taken into account when targeting it:

• WebAssembly is still at an early stage, so many features you'd be expect from other platforms are not available yet, specifically:
  1. wasm64 variant is not specified yet, only the 32-bit wasm32 variant is supported in WebAssembly hosts such as browsers.
  2. While a preview of multi-threading and atomics is available in some browsers and stand-alone WebAssembly hosts, the corresponding proposal haven't formally reached the implementation phase yet. The multi-threading feature is available in wasm32-unknown-wasip1-threads target, but it's not in wasm32-unknown-wasi target.
  3. Dynamic linking is not formally specified and tooling for it is not available yet.
• Binary size is a high priority requirement. Since WebAssembly payloads are usually served in browsers, one wouldn't want end users to download multi-megabyte binaries.

Building Swift SDK for WebAssembly

The Swift SDK for WebAssembly is built using the following command:

./utils/build-script --build-wasm-stdlib

This command will build the Swift compiler for the host platform and then build the Swift standard library for WebAssembly targets. The resulting Swift SDK .artifactbundle will be placed in the ../swift-sdk-generator/Bundles directory.

Building Swift SDK for WebAssembly without building the compiler

Building the Swift compiler is a time-consuming process. If you only want to build the Swift standard library with pre-built Swift compiler, you can use the following command:

$ SWIFT_TOOLS_PATH=path/to/swift-development-snapshot/usr/bin
$ ./utils/build-script \
    --skip-build-llvm \
    --skip-build-swift \
    --skip-build-cmark \
    --build-wasm-stdlib \
    --native-swift-tools-path="$SWIFT_TOOLS_PATH" \
    --native-clang-tools-path="$SWIFT_TOOLS_PATH" \
    --native-llvm-tools-path="$SWIFT_TOOLS_PATH"

Notes on the implementation

Here we're describing some decisions that were made while developing the implementation.

Relative Pointers

Relative pointers are used in Swift runtime, but currently it's not feasible to use them for some cases where the pointee is a function pointer. The reason is that WebAssembly has a separate address space for functions and data, and the offset bwtween a function and a data pointer cannot be defined. Therefore, we have to use absolute pointers for function pointers in WebAssembly (see include/swift/ABI/CompactFunctionPointer.h for more details).