|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +date: 2025-06-01 12:00:00 |
| 4 | +title: Getting Started with Swift SDKs for WebAssembly |
| 5 | +author: [maxdesiatov] |
| 6 | +--- |
| 7 | + |
| 8 | +[WebAssembly (Wasm) is a virtual instruction set](https://webassembly.org/) focused on portability, security, and |
| 9 | +performance. Developers can build client and server applications for Wasm and then deploy them in the browser or other |
| 10 | +Wasm runtime implementations. |
| 11 | + |
| 12 | +WebAssembly support in Swift started out as a community project. Any instruction set benefits tremendously from a |
| 13 | +standardized ABI and system interfaces, and from its inception Wasm support in Swift targeted [WebAssembly System |
| 14 | +Interface](https://wasi.dev/), which made porting Swift core libraries to this platform much easier. |
| 15 | + |
| 16 | +With Swift 6.2 and development snapshots you can easily cross-compile and run Wasm modules with Swift SDKs for WASI distributed on [swift.org](https://swift.org/download). |
| 17 | +The distributed artifact bundles also include support for the experimental Embedded Swift mode. |
| 18 | + |
| 19 | +## Installation |
| 20 | + |
| 21 | +1. [Install `swiftly` per the instructions](https://www.swift.org/install/) for the platform that you're bulding on. |
| 22 | + |
| 23 | +2. Install latest 6.2 development snapshot with `swiftly install 6.2-snapshot`, note the exact snapshot date component in the output of this command. |
| 24 | + |
| 25 | +3. Select the installed toolchain with `swiftly use 6.2-snapshot`. |
| 26 | + |
| 27 | +4. Navigate to [the downloads page](https://www.swift.org/download/) and find the “Swift SDK for WASI” section. Find a URL of a version that exactly matches the version from step 2. |
| 28 | +If the corresponding snapshot version is not available for the Swift SDK, you’ll have to install the matching toolchain first. |
| 29 | + |
| 30 | +5. Find the checksum value for the corresponding Swift SDK on the same page, substitute it together with the URL from step 2, and execute the following command: |
| 31 | + |
| 32 | + ``` |
| 33 | + swift sdk install <swift_sdk_url> --checksum <checksum_value> |
| 34 | + ``` |
| 35 | +
|
| 36 | +6. Run `swift sdk list` to verify the Swift SDK was installed and note its ID in the output. Two Swift SDKs will be installed, |
| 37 | +one with support for all Swift features, and the other with a subset of features allowed in the experimental [Embedded Swift mode](#embedded-swift-support). |
| 38 | +
|
| 39 | + | Swift SDK ID | Description | |
| 40 | + |:-------:|:-----------:| |
| 41 | + | `swift-<version>_wasm` | Supports all Swift features | |
| 42 | + | `swift-<version>_wasm-embedded` | Supports a subset of features allowed in the experimental [Embedded Swift mode](#embedded-swift-support) | |
| 43 | +
|
| 44 | +7. In the future, after installing or selecting a new version of the toolchain with `swiftly` make sure to follow steps 3-6 to install a Swift SDK exactly matching the toolchain version. |
| 45 | +
|
| 46 | +## Building and Running |
| 47 | +
|
| 48 | +Let's create a simple package to see the Swift SDK in action: |
| 49 | +
|
| 50 | +``` |
| 51 | +mkdir Hello |
| 52 | +cd Hello |
| 53 | +swift package init --type executable |
| 54 | +``` |
| 55 | +
|
| 56 | +Modify freshly created `Sources/Hello/Hello.swift` file to print different strings depending on the target |
| 57 | +platform: |
| 58 | +
|
| 59 | +```swift |
| 60 | +@main |
| 61 | +struct wasi_test { |
| 62 | + static func main() { |
| 63 | +#if os(WASI) |
| 64 | + print("Hello from WASI!") |
| 65 | +#else |
| 66 | + print("Hello from the host system!") |
| 67 | +#endif |
| 68 | + } |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +Build your package with the following command, substituting the ID from step 5 of [the "Installation" section](#installation) above. |
| 73 | + |
| 74 | +``` |
| 75 | +swift build --swift-sdk <swift_sdk_id> |
| 76 | +``` |
| 77 | + |
| 78 | +Recent toolchain snapshots that are compatible with Swift SDKs for WASI also include |
| 79 | +[WasmKit](https://github.com/swiftwasm/wasmkit/), which is a Wasm runtime that `swift run` can delegate to for |
| 80 | +execution. To run the freshly built module, use `swift run` with the same `--swift-sdk` option: |
| 81 | + |
| 82 | +``` |
| 83 | +swift run --swift-sdk <swift_sdk_id> |
| 84 | +``` |
| 85 | + |
| 86 | +You should see the following output: |
| 87 | + |
| 88 | +``` |
| 89 | +[1/1] Planning build |
| 90 | +Building for debugging... |
| 91 | +[8/8] Linking Hello.wasm |
| 92 | +Build of product 'Hello' complete! (1.31s) |
| 93 | +Hello from WASI! |
| 94 | +``` |
| 95 | + |
| 96 | +# Embedded Swift Support |
| 97 | + |
| 98 | +[Embedded Swift](https://github.com/swiftlang/swift-evolution/blob/main/visions/embedded-swift.md) is an experimental subset of the language |
| 99 | +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 |
| 100 | +with the `swift sdk install` command is tailored specifically for Embedded Swift. A subset of Swift Concurrency is also supported in this mode |
| 101 | +thanks to the functionality provided by WASI. |
| 102 | + |
| 103 | +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. You also have to pass `-c release` |
| 104 | +to `swift build` and `swift run` to enable optimizations required for Embedded Swift. |
| 105 | + |
0 commit comments