diff --git a/_data/authors.yml b/_data/authors.yml index 5e8313077..944b0cd9f 100644 --- a/_data/authors.yml +++ b/_data/authors.yml @@ -490,7 +490,7 @@ george-barnett: gus-cairo: name: Gus Cairo github: gjcairo - + vrylko: name: Vojtěch Rylko github: vojtarylko @@ -510,6 +510,10 @@ parispittman: name: Paris Pittman github: parispittman +maxdesiatov: + name: Max Desiatov + github: maxdesiatov + rmondello: name: Ricky Mondello github: rmondello diff --git a/_data/documentation.yaml b/_data/documentation.yaml index 850ccad66..cb8bf73be 100644 --- a/_data/documentation.yaml +++ b/_data/documentation.yaml @@ -67,6 +67,10 @@ description: | Learn how to get started building binaries for Linux with no system dependencies (not even the Swift runtime or C library). Even better, you can do this from any system with a Swift toolchain, allowing you to develop on macOS or Windows and easily deploy to Linux when you go to production. + - title: Getting Started with Swift SDKs for WebAssembly + url: /documentation/articles/wasm-getting-started.html + description: | + Learn how to get started building Swift packages for WebAssembly (Wasm). #---------------------------------------------------- - header: Contributing pages: diff --git a/documentation/articles/wasm-getting-started.md b/documentation/articles/wasm-getting-started.md new file mode 100644 index 000000000..88e571e83 --- /dev/null +++ b/documentation/articles/wasm-getting-started.md @@ -0,0 +1,105 @@ +--- +layout: page +date: 2025-06-01 12:00:00 +title: Getting Started with Swift SDKs for WebAssembly +author: [maxdesiatov] +--- + +[WebAssembly (Wasm) is a virtual instruction set](https://webassembly.org/) 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](https://wasi.dev/), which made porting Swift core libraries to this platform much easier. + +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). +The distributed artifact bundles also include support for the experimental Embedded Swift mode. + +## Installation + +1. [Install `swiftly` per the instructions](https://www.swift.org/install/) for the platform that you're bulding on. + +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. + +3. Select the installed toolchain with `swiftly use 6.2-snapshot`. + +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. +If the corresponding snapshot version is not available for the Swift SDK, you’ll have to install the matching toolchain first. + +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: + + ``` + swift sdk install --checksum + ``` + +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, +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). + + | Swift SDK ID | Description | + |:-------:|:-----------:| + | `swift-_wasm` | Supports all Swift features | + | `swift-_wasm-embedded` | Supports a subset of features allowed in the experimental [Embedded Swift mode](#embedded-swift-support) | + +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. + +## 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: + +```swift +@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](#installation) above. + +``` +swift build --swift-sdk +``` + +Recent toolchain snapshots that are compatible with Swift SDKs for WASI also include +[WasmKit](https://github.com/swiftwasm/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 +``` + +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](https://github.com/swiftlang/swift-evolution/blob/main/visions/embedded-swift.md) 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. A subset of Swift Concurrency is also supported in this mode +thanks to the functionality provided by WASI. + +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` +to `swift build` and `swift run` to enable optimizations required for Embedded Swift. +