WASI SDK

When developing with WASI SDK, be aware of the following constraints:

• C++ Exceptions: Disabled by default. Requires extra configuration.
• setjmp/longjmp: Requires extra configuration.
• Threading: Most targets do not support spawning threads. Experimental support is available via the wasm32-wasip1-threads target (using wasi-threads).
  • The pthread_* family and C++ primitives (<atomic>, <mutex>, <thread>) are available on all targets.
  • To catch errors when building for single-threaded targets, define the macro _WASI_STRICT_PTHREAD to make threading functions fail at compile time.
• Dynamic Linking: Supported, but less mature than static linking; may contain obscure bugs.
• Networking: WASIp1 targets do not support networking. WASIp2/WASIp3 support networking.
• 64-bit Memory: wasm64 targets are not currently supported.

You can use the official WASI SDK Docker image to build projects without a local installation. The image includes Autotools, CMake, and Ninja, and sets standard environment variables for the SDK.

To build a make-based project:

docker run -v `pwd`:/src -w /src ghcr.io/webassembly/wasi-sdk make

Note: Many projects may require disabling threads in their configure step to work with WASI SDK.

When using CMake, you can set up the WASI SDK platform by passing the CMAKE_TOOLCHAIN_FILE variable pointing to the appropriate .cmake file in the SDK's share/cmake/ directory.

For the standard platform:

cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk.cmake ...

For the platform with thread support (wasi-sdk-thread):

cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk-pthread.cmake ...

$ cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk.cmake ...

$ cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk-pthread.cmake ...

Starting from wasi-sdk-33, the sysroot contains two copies of the C++ standard library: one with exceptions enabled and one with exceptions disabled. By default, exceptions are disabled. To enable C++ exceptions, you must provide specific compilation and linking flags to ensure the correct standard library is selected and WebAssembly exception-handling instructions are used.

Required flags:

• -fwasm-exceptions: Enables the WebAssembly exception-handling proposal and selects the correct C++ standard library during linking.
• -mllvm -wasm-use-legacy-eh=false: Forces the use of standard WebAssembly exception-handling instructions instead of the legacy proposal.
• -lunwind: Links the unwinding support required for C++ exceptions.

$ export CFLAGS="-fwasm-exceptions -mllvm -wasm-use-legacy-eh=false"
$ export LDFLAGS="-fwasm-exceptions -lunwind"

When building the wasi-sdk sysroot from source, you can enable support for C++ exceptions by passing the -DWASI_SDK_EXCEPTIONS=ON CMake flag. This compiles the C++ standard library with exception support for the target architectures.

Requirement: Enabling C++ exceptions requires LLVM 22 or later.

$ cmake -G Ninja -B build/sysroot -S . \
    -DCMAKE_TOOLCHAIN_FILE=$path/to/wasi-sdk-p1.cmake \
    -DWASI_SDK_EXCEPTIONS=ON

To install the WASI SDK, download the appropriate tarball from the GitHub releases page based on your OS and architecture, then extract it.

Example for Linux x86_64 (version 27):

WASI_OS=linux
WASI_ARCH=x86_64 # or 'arm64' if running on arm64 host
WASI_VERSION=27
WASI_VERSION_FULL=${WASI_VERSION}.0
wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_VERSION}/wasi-sdk-${WASI_VERSION_FULL}-${WASI_ARCH}-${WASI_OS}.tar.gz
tar xvf wasi-sdk-${WASI_VERSION_FULL}-${WASI_ARCH}-${WASI_OS}.tar.gz

To use setjmp and longjmp in your WebAssembly applications, you must provide specific compiler and linker flags. WASI-SDK implements this by using a compiler pass that replaces setjmp calls with a specialized implementation provided by wasi-libc via the -lsetjmp library.

By default, the compiler emits legacy exception-handling instructions. To use the modern WebAssembly exception-handling specification (Phase 5), you must explicitly set -mllvm -wasm-use-legacy-eh=false.

Users of C++ exceptions in wasi-sdk should be aware of the following current limitations:

• No Shared Libraries: C++ exception support does not currently work with shared libraries.
• Flag Requirements: -fwasm-exceptions is strictly required to enable exceptions; -fexceptions is not currently a supported substitute.
• Unwinding Linkage: -lunwind must be explicitly passed during the linking stage.
• LTO Conflict: There is a known issue where exceptions and Link Time Optimization (LTO) may not work together. See issue #629 for details.

When using Link Time Optimization (-flto=full), you must pass the -mllvm flags to both the compiler and the linker. This ensures the setjmp transformation and exception-handling instruction selection are correctly applied during the linking stage.

clang -Os -flto=full -o test.wasm test.c \
    -mllvm -wasm-enable-sjlj -lsetjmp -mllvm -wasm-use-legacy-eh=false \
    -Wl,-mllvm,-wasm-enable-sjlj,-mllvm,-wasm-use-legacy-eh=false

To compile code, use the clang binary located in the bin directory of your WASI SDK installation. You must specify the --sysroot pointing to the share/wasi-sysroot directory within the SDK.

Note: If the SDK is installed at /opt/wasi-sdk, the --sysroot flag is not required.

WASI_SDK_PATH=`pwd`/wasi-sdk-${WASI_VERSION_FULL}-${WASI_ARCH}-${WASI_OS}
CC="${WASI_SDK_PATH}/bin/clang --sysroot=${WASI_SDK_PATH}/share/wasi-sysroot"
$CC foo.c -o foo.wasm