Introduction

Welcome to the SwiftWasm Documentation!

SwiftWasm is an open source project to support the WebAssembly target for Swift.

The goal of this project is to fully support the WebAssembly target for Swift and to be merged into the upstream repository.

Getting Started (with Nightly Toolchain)

Installation

You can install latest toolchain of SwiftWasm from Release Page

The toolchains can be installed via swiftenv like official nightly toolchain.

Here's an example swiftenv invocation for installing the latest stable SwiftWasm toolchain on macOS Catalina:


$ swiftenv install \
  https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.3-SNAPSHOT-2020-08-15-a/swift-wasm-5.3-SNAPSHOT-2020-08-15-a-osx.tar.gz
$ swift --version
Swift version 5.3-dev (LLVM ba56ef042e, Swift 5855a96018)
Target: x86_64-apple-darwin19.3.0

Hello, World!

$ echo 'print("Hello, world!")' > hello.swift
# Compile Swift code into WebAssembly with WASI
$ TOOLCHAIN_PATH=$(dirname $(swiftenv which swiftc))/../
$ swiftc \
    -target wasm32-unknown-wasi \
    -sdk $TOOLCHAIN_PATH/share/wasi-sysroot \
    hello.swift -o hello.wasm

You can the run the produced binary with wasmer (or other WebAssembly runtime):

$ wasmer hello.wasm

The produced binary depends on WASI which is an interface of system call for WebAssembly. So you need to use WASI supported runtime and when you run the binary on browser, you need WASI polyfill library like @wasmer/wasi.

Swift Package Manager

You can also use SwiftPM for managing packages in the same way as other platforms.

$ swiftenv local wasm-DEVELOPMENT-SNAPSHOT-2020-06-07-a
$ swift package init --type executable
$ swift build --triple wasm32-unknown-wasi
$ wasmer ./.build/debug/hello-swiftwasm
Hello, world!

JavaScript Bindings

JavaScriptKit is Swift framework to interact with JavaScript through WebAssembly.

You can use any JavaScript API from Swift using this library.

Development Guide

Forum posts

Repositories

swiftwasm/swift

The main repository of this project. Forked from apple/swift. We are tracking upstream changes using pull

Branching scheme

  • swiftwasm is the main develop branch
  • master is a mirror of the master branch of the upstream apple/master repository. This branch is necessary to avoid some issues
  • swiftwasm-release/5.3 is the branch where 5.3 release of SwiftWasm is prepared.
  • release/5.3 is a mirror of the upstream release/5.3 branch.

swiftwasm/llvm-project

Forked from apple/llvm-project.

swiftwasm branch is based on swift/master branch of apple/llvm-project.

Please see AppleBranchingScheme.md

swiftwasm/icu4c-wasi

Build script and patches for building ICU project for WebAssembly

We are sending patches to upstream repository.

  • https://github.com/unicode-org/icu/pull/990

swiftwasm/wasi-sdk and swiftwasm/wasi-libc

Forked from WebAssembly/wasi-sdk and WebAssembly/wasi-libc.

We fork them to build wasi-sysroot with pthread header. There aren't so many diff from upstream.

How to build

First, checkout the project source code.

$ mkdir swiftwasm-source
$ cd swiftwasm-source
$ git clone https://github.com/swiftwasm/swift.git
$ ./swift/utils/update-checkout --scheme wasm --clone

Before building Swift, please install required dependencies.

# On macOS
$ ./utils/webassembly/macos/install-dependencies.sh
# On Linux
$ ./utils/webassembly/linux/install-dependencies.sh

We support both Linux and macOS to build Swift. These script wraps ./utils/build-script to simplify build options. You can pass additional build-script options through these scripts.

# On macOS
$ ./utils/webassembly/build-mac.sh -R
# On Linux
$ ./utils/webassembly/build-linux.sh -R

If you want to get more information about build system, please feel free to ask @kateinoigakukun on Twitter.

Development Tips

Cache

Compilation time of LLVM project is very long, so we recommend to cache the artifact using sccache

Use sccache to cache build artifacts

Debugging

When you want to debug a WebAssembly binary, wasminspect is very helpful to investigate.

Continuous Integration

We use GitHub Actions to build and run tests continuously. (But jobs without cache takes 3~4 hours to be completed)

Currently (2020/03/12), running test on Linux is disabled because the job exection time and storage reached the limit of GitHub Actions.

References