Quick Start
About this repository
This repository contains no compiler or library code itself; it uses git submodules to pull in the upstream Clang and LLVM tree, as well as the wasi-libc tree.
The libc portion of this SDK is maintained in
.
Upstream Clang and LLVM (from 9.0 onwards) can compile for WASI out of the box, and WebAssembly support is included in them by default. So, all that's done here is to provide builds configured to set the default target and sysroot for convenience.
One could also use a standard Clang installation, build a sysroot from the sources mentioned above, and compile with --target=wasm32-wasip1 --sysroot=/path/to/sysroot. In this scenario, one would also need the libclang_rt.*.a objects available separately in the
which must be extracted into $CLANG_INSTALL_DIR/$CLANG_VERSION/lib/.
Clone
This repository uses git submodule, to clone it you need use the command below :
git clone --recursive https://github.com/WebAssembly/wasi-sdk.gitRequirements
The Wasm-sdk's build process needs some packages :
cmake
clang
ninja
python3
cargo
Please refer to your OS documentation to install those packages.
Build
Building wasi-sdk uses CMake and is split into two halves. First you can build the toolchain itself:
cmake -G Ninja -B build/toolchain -S . -DWASI_SDK_BUILD_TOOLCHAIN=ON -DCMAKE_INSTALL_PREFIX=build/install cmake --build build/toolchain --target installWhen you're developing locally you may also wish to pass -DCMAKE_CXX_COMPILER_LAUNCHER=ccache to assist with rebuilds. Other supported CMake flags are:
-DLLVM_CMAKE_FLAGS - extra flags to pass to cmake when building LLVM/Clang.
-DRUST_TARGET - the specific Rust target triple to build wasm-component-ld for, useful for cross-compiles.
The clang compiler should now be located at build/install/bin/clang but it's just a compiler, the sysroot isn't built yet. Next the second step of the build is to build the sysroot:
cmake -G Ninja -B build/sysroot -S . \ -DCMAKE_INSTALL_PREFIX=build/install \ -DCMAKE_TOOLCHAIN_FILE=build/install/share/cmake/wasi-sdk-p2.cmake \ -DCMAKE_C_COMPILER_WORKS=ON \ -DCMAKE_CXX_COMPILER_WORKS=ON cmake --build build/sysroot --target installA full toolchain should now be present at build/install and is ready for use in compiling WebAssembly code. Supported CMake flags are:
-DWASI_SDK_DEBUG_PREFIX_MAKE=OFF - disable -fdebug-prefix-map when building C/C++ code to use full host paths instead.
-DWASI_SDK_INCLUDE_TESTS=ON - used for building tests.
-DWASI_SDK_CPU_CFLAGS=.. - used to specify CFLAGS to tweak wasm features to enable/disable. The default is -mcpu=lime1.
-DWASI_SDK_LTO=ON - whether to enable/disable builds of LTO-capable libraries as part of the build.
-DWASI_SDK_BUILD_SHARED=ON - whether to build shared libraries (libc.so, libc++.so, etc.) for targets that support them. Set to OFF to produce a static-only sysroot.
-DWASI_SDK_EXCEPTIONS=ON - whether to enable/disable support for C++ exceptions, see
for more information.
-DWASI_SDK_TEST_HOST_TOOLCHAIN=ON - test the host toolchain's wasi-libc and sysroot libraries, don't build or use fresh libraries for tests.
-DWASI_SDK_TARGETS=.. - a list of targets to build, by default all WASI targets are compiled. The default set is listed in
.
-DWASI_SDK_INSTALL_TO_CLANG_RESOURCE_DIR=ON - install compiler-rt to the compiler's resource directory. might be convenient if you want to use the toolchain (eg. ./build/install/bin/clang) in-place.
If you'd like to build distribution artifacts you can use the dist target like so:
cmake --build build/toolchain --target dist cmake --build build/sysroot --target distTarballs will be created under build/toolchain/dist and build/sysroot/dist. Note that these are separate tarballs for the toolchain and sysroot. To create a single tarball for the entire SDK you'll first want to copy all tarballs into a new folder and then run the ./ci/merge-artifacts.sh script:
mkdir dist-my-platform cp build/toolchain/dist/* build/sysroot/dist/* dist-my-platform ./ci/merge-artifacts.shThis will produce dist/wasi-sdk-*.tar.gz which is the same as the release artifacts for this repository.
Finally you can additionally bundle many of the above steps, minus merge-artifact.sh by using the CI script to perform both the toolchain and sysroot build:
./ci/build.shThe built package can be found into build/dist directory. For releasing a new version of the package on GitHub, see
.
Install
A typical installation from the release binaries might look like the following:
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.gzUse
Use the clang installed in the wasi-sdk directory:
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.wasmNote: ${WASI_SDK_PATH}/share/wasi-sysroot contains the WASI-specific includes/libraries/etc. The --sysroot=... option is not necessary if WASI_SDK_PATH is /opt/wasi-sdk. For troubleshooting, one can replace the --sysroot path with a manual build of
.
Supported Targets
The default target for the SDK's clang is wasm32-wasip1. The default WASI_SDK_TARGETS build setting includes these targets:
TargetDescriptionwasm32-wasip1WASI Preview 1, and the default target.wasm32-wasip2WASI Preview 2 and the component model.wasm32-wasip3WASI Preview 3 and async component model support.wasm32-wasip1-threadsWASI Preview 1 with experimental support for spawning threads.As of wasi-sdk 34, the previously supported wasm32-wasi and wasm32-wasi-threads aliases have been removed. Use wasm32-wasip1 and wasm32-wasip1-threads instead.
To build only a subset of targets, pass a semicolon-separated WASI_SDK_TARGETS value when configuring the sysroot:
cmake -G Ninja -B build/sysroot -S . \ -DCMAKE_INSTALL_PREFIX=build/install \ -DCMAKE_TOOLCHAIN_FILE=build/install/share/cmake/wasi-sdk-p1.cmake \ -DWASI_SDK_TARGETS="wasm32-wasip1;wasm32-wasip2" \ -DCMAKE_C_COMPILER_WORKS=ON \ -DCMAKE_CXX_COMPILER_WORKS=ONIntegrating with a CMake build system
Use a toolchain file to setup the wasi-sdk platform.
$ cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk.cmake ... For WASI Preview 2 or Preview 3, use the corresponding toolchain file:
$ cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk-p2.cmake ... $ cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk-p3.cmake ... For the threaded Preview 1 target, use the wasi-sdk-thread platform:
$ cmake -DCMAKE_TOOLCHAIN_FILE=${WASI_SDK_PATH}/share/cmake/wasi-sdk-pthread.cmake ... Notes for Autoconf
2.70 now
.
For convenience when building packages that aren't yet updated, updated config.sub and config.guess files are installed at share/misc/config.* in the install directory.
Docker Image
We provide a
including WASI SDK that can be used for building projects without a separate installation of the SDK. Autotools, CMake, and Ninja are included in this image, and standard environment variables are set to use WASI SDK for building.
For example, this command can build a make-based project with the Docker image.
docker run -v `pwd`:/src -w /src ghcr.io/webassembly/wasi-sdk make Take note of the
below when building projects, for example many projects will need threads support disabled in a configure step before building with WASI SDK.
Notable Limitations
C++ exceptions are disabled by default and require extra configuration to get working, see [CppExceptions.md].
C setjmp/longjmp require some extra configuration to get working, see [SetjmpLongjmp.md].
Most targets do not support spawning a thread. Experimental support for spawning threads is available with the wasm32-wasip1-threads target which uses
. Note that the pthread_* family of functions, as well as C++ threading primitives such as <atomic>, <mutex>, and <thread> are available on all targets. Defining a macro _WASI_STRICT_PTHREAD will make pthread_create, pthread_detach, pthread_join, pthread_tryjoin_np, and pthread_timedjoin_np fail with a compile time error when building for single-threaded targets.
Dynamic linking
but not as fully baked as static linking. There might be obscure bugs in some situations related to dynamic linking.
The WASIp1 targets do not support networking, but WASIp2/WASIp3 support networking.
64-bit linear memories (a "wasm64" target) are not supported at this time. Supporting this will require resolving
WebAssembly/component-model#22
first at which point it will be possible to add a wasm64-wasip2 target. There are no plans to add support for wasm64-wasi{,-threads,p1,p1-threads} at this time.