|
1 | | -# Installation - Latest Release (SwiftWasm 5.10) |
| 1 | +# Installation - Latest Release (Swift 6.0.3) |
2 | 2 |
|
3 | | -To install Swift for WebAssembly toolchain, download one of the packages below and follow the instructions for your operating system. |
| 3 | +SwiftWasm provides [Swift SDK](https://github.com/apple/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md)s for WebAssembly. |
4 | 4 |
|
5 | | -Tag: [swift-wasm-5.10.0-RELEASE](https://github.com/swiftwasm/swift/releases/tag/swift-wasm-5.10.0-RELEASE) |
| 5 | +Before installing the Swift SDK, you need to ensure the following: |
6 | 6 |
|
7 | | -| Download | Docker Tag | |
8 | | -|:------------------:|:----------:| |
9 | | -| [macOS arm64](https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.10.0-RELEASE/swift-wasm-5.10.0-RELEASE-macos_arm64.pkg) | Unavailable | |
10 | | -| [macOS x86](https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.10.0-RELEASE/swift-wasm-5.10.0-RELEASE-macos_x86_64.pkg) | Unavailable | |
11 | | -| [Ubuntu 18.04 x86_64](https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.10.0-RELEASE/swift-wasm-5.10.0-RELEASE-ubuntu18.04_x86_64.tar.gz) | [5.10-bionic, bionic](https://github.com/orgs/swiftwasm/packages/container/package/swift) | |
12 | | -| [Ubuntu 20.04 x86_64](https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.10.0-RELEASE/swift-wasm-5.10.0-RELEASE-ubuntu20.04_x86_64.tar.gz) | [5.10-focal, focal](https://github.com/orgs/swiftwasm/packages/container/package/swift) | |
13 | | -| [Ubuntu 20.04 aarch64](https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.10.0-RELEASE/swift-wasm-5.10.0-RELEASE-ubuntu20.04_aarch64.tar.gz) | [5.10-focal, focal](https://github.com/orgs/swiftwasm/packages/container/package/swift) | |
14 | | -| [Ubuntu 22.04 x86_64](https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.10.0-RELEASE/swift-wasm-5.10.0-RELEASE-ubuntu22.04_x86_64.tar.gz) | [5.10, 5.10-jammy, jammy, latest](https://github.com/orgs/swiftwasm/packages/container/package/swift) | |
| 7 | +- You need to [install an Open Source toolchain from swift.org](https://www.swift.org/install/). (Not the Xcode toolchain) |
| 8 | +- You cannot use toolchains bundled with Xcode to use the Swift SDK. |
| 9 | +- If you are using macOS, please follow the [official guide](https://www.swift.org/install/macos/package_installer/) to install the toolchain. |
15 | 10 |
|
16 | | - |
17 | | -You can find older releases from the [GitHub Releases page](https://github.com/swiftwasm/swift/releases?q=prerelease%3Afalse) |
18 | | - |
19 | | -## Toolchain Installation |
20 | | - |
21 | | -### macOS |
22 | | - |
23 | | -1. [Download the latest package release](#latest-release) according to your CPU architecture (arm64 for [Apple Silicon Macs](https://support.apple.com/en-us/HT211814), x86 for Intel Macs). |
24 | | -2. Run the package installer, which will install an Xcode toolchain into `/Library/Developer/Toolchains/`. |
25 | | -3. To use the Swift toolchain with command-line tools, use `env TOOLCHAINS=swiftwasm swift` or add the Swift toolchain to your path as follows: |
| 11 | +Once you have installed the Open Source toolchain, you can install the Swift SDK for WebAssembly: |
26 | 12 |
|
27 | 13 | ```bash |
28 | | -export PATH=/Library/Developer/Toolchains/<toolchain name>.xctoolchain/usr/bin:"${PATH}" |
| 14 | +$ swift sdk install "https://github.com/swiftwasm/swift/releases/download/swift-wasm-6.0.3-RELEASE/swift-wasm-6.0.3-RELEASE-wasm32-unknown-wasi.artifactbundle.zip" --checksum "31d3585b06dd92de390bacc18527801480163188cd7473f492956b5e213a8618" |
29 | 15 | ``` |
30 | 16 |
|
31 | | -4. Run `swift --version`. If you installed the toolchain successfully, you can get the following message. |
| 17 | +After installing the Swift SDK, you can see the installed SDKs: |
32 | 18 |
|
33 | 19 | ```bash |
34 | | -$ swift --version |
35 | | -# Or TOOLCHAINS=swiftwasm swift --version |
36 | | -SwiftWasm Swift version 5.10-dev |
37 | | -Target: x86_64-apple-darwin21.6.0 |
| 20 | +$ swift sdk list |
| 21 | +<SDK name> |
| 22 | +... |
38 | 23 | ``` |
39 | 24 |
|
40 | | -If you want to uninstall the toolchain, you can remove the toolchain directory from `/Library/Developer/Toolchains/` and make sure to remove the toolchain from your `PATH`. |
41 | | - |
42 | | -## Linux |
| 25 | +You can also find other SDKs from [the GitHub Releases page](https://github.com/swiftwasm/swift/releases). |
43 | 26 |
|
44 | | -1. [Download the latest package release](#latest-release) according to your Ubuntu version and CPU architecture. |
45 | | -2. Follow the official Swift installation guide for Linux from [swift.org](https://www.swift.org/install/linux/#installation-via-tarball) while skipping GPG key verification, which is not provided for SwiftWasm releases. |
| 27 | +Use the following shell snippet to query compatible Swift SDK for your current toolchain version: |
46 | 28 |
|
47 | | -## Experimental: Swift SDK |
| 29 | +```console |
| 30 | +( |
| 31 | + V="$(swiftc --version | head -n1)"; \ |
| 32 | + TAG="$(curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/tag-by-version.json" | jq -r --arg v "$V" '.[$v] | .[-1]')"; \ |
| 33 | + curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/builds/$TAG.json" | \ |
| 34 | + jq -r '.["swift-sdks"]["wasm32-unknown-wasi"] | "swift sdk install \"\(.url)\" --checksum \"\(.checksum)\""' |
| 35 | +) |
| 36 | +``` |
48 | 37 |
|
49 | | -SwiftWasm provides [Swift SDK](https://github.com/apple/swift-evolution/blob/main/proposals/0387-cross-compilation-destinations.md)s for WebAssembly. You can use the Swift SDK to cross-compile Swift packages for WebAssembly without installing the whole toolchain. |
| 38 | +## Hello, World |
50 | 39 |
|
51 | | -To use the Swift SDK, you need to install the official Swift toolchain 5.10 or later. Then, you can install the Swift SDK using the following command while replacing `<your platform>`: |
| 40 | +First, create a new directory for your project and navigate into it: |
52 | 41 |
|
53 | 42 | ```bash |
54 | | -$ swift experimental-sdk install https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.10.0-RELEASE/swift-wasm-5.10.0-RELEASE-<your platform>.artifactbundle.zip |
| 43 | +$ mkdir hello && cd hello |
55 | 44 | ``` |
56 | 45 |
|
57 | | -You can find the latest Swift SDK release from [the GitHub Releases page](https://github.com/swiftwasm/swift/releases/tag/swift-wasm-5.10.0-RELEASE). |
| 46 | +Create a new Swift package: |
58 | 47 |
|
59 | | -After installing the Swift SDK, you can see the installed SDKs using the following command: |
| 48 | +```bash |
| 49 | +$ swift package init --type executable |
| 50 | +``` |
| 51 | + |
| 52 | +You can use the installed SDKs to cross-compile Swift packages for WebAssembly: |
60 | 53 |
|
61 | 54 | ```bash |
62 | | -$ swift experimental-sdk list |
63 | | -<SDK name> |
| 55 | +$ swift build --swift-sdk wasm32-unknown-wasi |
64 | 56 | ... |
| 57 | +$ file .build/wasm32-unknown-wasi/debug/hello.wasm |
| 58 | +.build/wasm32-unknown-wasi/debug/hello.wasm: WebAssembly (wasm) binary module version 0x1 (MVP) |
65 | 59 | ``` |
66 | 60 |
|
67 | | -You can use the installed SDKs to cross-compile Swift packages for WebAssembly using the following command: |
| 61 | +You can run the built WebAssembly module using [`wasmtime`](https://wasmtime.dev/): |
68 | 62 |
|
69 | 63 | ```bash |
70 | | -$ swift build --experimental-swift-sdk <SDK name> |
| 64 | +$ wasmtime .build/wasm32-unknown-wasi/debug/hello.wasm |
| 65 | +Hello, world! |
71 | 66 | ``` |
72 | 67 |
|
73 | | -## Docker |
| 68 | +## FAQ |
74 | 69 |
|
75 | | -SwiftWasm offical Docker images are hosted on [GitHub Container Registry](https://github.com/orgs/swiftwasm/packages/container/package/swift). |
| 70 | +### How to check if I am using Open Source toolchain or Xcode toolchain? |
76 | 71 |
|
77 | | -SwiftWasm Dockerfiles are located on [swiftwasm-docker](https://github.com/swiftwasm/swiftwasm-docker) repository. |
| 72 | +```bash |
| 73 | +$ swift --version | head -n1 |
| 74 | +``` |
78 | 75 |
|
79 | | -### Supported Platforms |
| 76 | +| Toolchain | Output | |
| 77 | +|-----------|--------| |
| 78 | +| Xcode | `Apple Swift version 6.0.3 (swiftlang-6.0.3.1.10 clang-1600.0.30.1)` | |
| 79 | +| Open Source (macOS) | `Apple Swift version 6.0.3 (swift-6.0.3-RELEASE)` | |
| 80 | +| Open Source (Others) | `Swift version 6.0.3 (swift-6.0.3-RELEASE)` | |
80 | 81 |
|
81 | | -- Ubuntu 18.04 (x86_64) |
82 | | -- Ubuntu 20.04 (x86_64, aarch64) |
83 | | -- Ubuntu 22.04 (x86_64) |
| 82 | +### What is the difference between the Swift Toolchain and the Swift SDK? |
84 | 83 |
|
85 | | -### Using Docker Images |
| 84 | +The Swift toolchain is a complete package that includes the Swift compiler, standard library, and other tools. |
86 | 85 |
|
87 | | -1. Pull the Docker image from [GitHub Container Registry](https://github.com/orgs/swiftwasm/packages/container/package/swift): |
| 86 | +The Swift SDK includes a subset of the Swift toolchain that includes only the necessary components for cross-compilation and some supplementary resources. |
88 | 87 |
|
89 | | -```bash |
90 | | -docker pull ghcr.io/swiftwasm/swift:latest |
91 | | -``` |
92 | | - |
93 | | -2. Create a container using tag `latest` and attach it to the container: |
| 88 | +### What is included in the Swift SDK for WebAssembly? |
94 | 89 |
|
95 | | -```bash |
96 | | -docker run --rm -it ghcr.io/swiftwasm/swift:latest /bin/bash |
97 | | -``` |
| 90 | +The Swift SDK for WebAssembly includes only the pre-built Swift standard libraries for WebAssembly. It does not include the Swift compiler or other tools that are part of the Swift toolchain. |
0 commit comments