wasi-sdk: Install and Build a WASI C/C++ Toolchain

wasi-sdk Removes Manual WASI Target and Sysroot Setup

wasi-sdk addresses a specific gap in the WebAssembly C and C++ build process. Upstream Clang and LLVM can compile for WASI, and WebAssembly support is included by default from LLVM 9.0 onward, but a usable toolchain still needs a sysroot containing WASI headers and libraries. It also needs compiler runtime objects in the expected Clang resource directory.

The repository supplies the build configuration used to assemble those parts. Its default `clang` target is `wasm32-wasip1`, and its sysroot contains the WASI-specific includes and libraries used during compilation. This is for developers who want to compile a C file or a C++ program to WebAssembly without manually reproducing a release sysroot and `libclang_rt.*.a` layout.

This repository does not contain compiler or library source code itself. Based on its `.gitmodules` entry and README, it pulls the upstream Clang and LLVM tree and the `wasi-libc` tree through Git submodules. The libc component is maintained separately in the `wasi-libc` repository. That division matters when assessing maintenance: changes to libc behavior come from that upstream project rather than from code stored directly in this repository.

The SDK is relevant when a build must target one of the supported WASI environments or the experimental threaded Preview 1 target. It is not a general WebAssembly package manager, runtime, or application bundler. Its scope is the compilation toolchain and sysroot.

wasi-sdk's Two-Stage Clang and Sysroot Build

Building from source is deliberately split into two stages. The first configures and installs the toolchain, including the `clang` executable. The second uses the newly installed CMake toolchain file to compile the sysroot. This order matters because the sysroot build depends on the toolchain produced by the first stage.

The required build tools listed by the README are `cmake`, `clang`, `ninja`, `python3`, and `cargo`. Since the project uses submodules, a shallow or incomplete clone may omit the LLVM and `wasi-libc` trees needed by CMake. The documented recursive clone is therefore the relevant installation path for contributors who intend to build the repository rather than download a release package.

The default SDK target set covers `wasm32-wasip1`, `wasm32-wasip2`, `wasm32-wasip3`, and `wasm32-wasip1-threads`. WASI Preview 2 is associated with the component model, while Preview 3 covers async component model support according to the supported-targets table. As of wasi-sdk 34, the older `wasm32-wasi` and `wasm32-wasi-threads` aliases have been removed. Scripts or build documentation that still invoke those names must be updated to use `wasm32-wasip1` and `wasm32-wasip1-threads`.

The sysroot can also be limited with `WASI_SDK_TARGETS`, a semicolon-separated CMake setting. Building only required targets can avoid unnecessary sysroot work, although the README does not quantify the resulting time saving.

Downloading and First Compiling a C File with wasi-sdk

For an initial use, the README recommends downloading a release archive rather than building LLVM from source. Its example selects release version 27, the `linux` OS, and either `x86_64` or `arm64` according to the host architecture. Change those variables only when the corresponding release archive is available.

This documented example downloads and extracts the archive:

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

After extraction, set `WASI_SDK_PATH` to the extracted `wasi-sdk` directory. The example stores `CC` as a command string rather than only an executable path, so it includes both the packaged `clang` and the sysroot option:

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

This compiles `foo.c` to `foo.wasm`. The README states that `${WASI_SDK_PATH}/share/wasi-sysroot` holds the WASI-specific headers, libraries, and related files. The explicit `--sysroot` option can be omitted when `WASI_SDK_PATH` is `/opt/wasi-sdk`. For troubleshooting, the README points to a manual `wasi-libc` build as an alternative sysroot path.

Building wasi-sdk from Its Git Submodules

Source builds are intended for contributors and for configurations that differ from a downloaded release. Start by cloning the repository recursively. The `--recursive` option is significant here because the repository obtains Clang, LLVM, and `wasi-libc` through submodules.

Use this command from the repository documentation:

git clone --recursive https://github.com/WebAssembly/wasi-sdk.git

The first CMake invocation creates the toolchain under `build/toolchain` and installs it under `build/install`:

cmake -G Ninja -B build/toolchain -S . -DWASI_SDK_BUILD_TOOLCHAIN=ON -DCMAKE_INSTALL_PREFIX=build/install
cmake --build build/toolchain --target install

At this point, the README places `clang` at `build/install/bin/clang`, but warns that this executable is not yet a complete setup because the sysroot has not been built. The second configure command uses `wasi-sdk-p2.cmake` and asks the build to install compiler-rt into Clang's resource directory:

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 \
    -DWASI_SDK_INSTALL_TO_CLANG_RESOURCE_DIR=ON
cmake --build build/sysroot --target install

The complete local package is then placed under `build/install`. A developer who needs to reproduce release artifacts can build the `dist` target for both halves, then combine the resulting archives with `./ci/merge-artifacts.sh`. The README notes that toolchain and sysroot archives are separate before that merge step.

Target, Library, Exception, and Thread Boundaries

wasi-sdk has several source-build switches that materially change its output. `-DWASI_SDK_BUILD_SHARED=ON` builds shared libraries such as `libc.so` and `libc++.so` for targets that support them. Setting it to `OFF` produces a static-only sysroot, which may be the appropriate boundary for a reproducible runtime package, although the README does not prescribe one mode.

C++ exception support can be enabled or disabled with `-DWASI_SDK_EXCEPTIONS=ON`. Projects should not assume that exception behavior is interchangeable across SDK configurations because the project treats it as an explicit build option and refers readers to `CppExceptions.md`. LTO-capable libraries can be included with `-DWASI_SDK_LTO=ON`.

Thread support is represented by `wasm32-wasip1-threads`, which the README labels experimental. A build intended for that target must account for experimental status rather than treating it as equivalent to the default Preview 1 environment. The removed `wasm32-wasi-threads` alias will not provide a migration path in wasi-sdk 34.

Other configuration points include `-DWASI_SDK_CPU_CFLAGS`, whose default is `-mcpu=lime1`, and `-DWASI_SDK_DEBUG_PREFIX_MAKE=OFF`, which retains full host paths instead of applying `-fdebug-prefix-map`. The latter can expose source paths in built C and C++ artifacts. For local rebuilds, `-DCMAKE_CXX_COMPILER_LAUNCHER=ccache` can assist with incremental compilation when `ccache` is available.

Maintenance Scope, License, and Upgrade Work

The repository is not archived, and its last push was on 2026-10-02. The release list includes wasi-sdk-34 on 2026-08-25, preceded by wasi-sdk-34-rc.3 on 2026-08-20 and wasi-sdk-34-rc.2 on 2026-07-22. Those dates establish recent repository activity, but they do not by themselves document compatibility guarantees for every application.

The repository is licensed under Apache-2.0. Its licensing and its use of upstream Clang, LLVM, and `wasi-libc` are separate considerations. The README states that the libc portion is maintained in `wasi-libc`; it does not provide a complete licensing analysis for every bundled component. Review the repository `LICENSE` and applicable upstream project terms before redistributing a built SDK.

An SDK upgrade can affect more than the compiler version. Release 34 removed the `wasm32-wasi` and `wasm32-wasi-threads` aliases, so target-name changes in build scripts are a concrete upgrade concern. Source builders can also change which sysroot targets, runtime objects, exceptions, shared libraries, or LTO libraries are produced by turning relevant CMake options on or off. Release users need to verify both the archive layout and their expected target before replacing an existing installation.

For teams that need custom combinations of exceptions, shared libraries, LTO, a restricted target set, or in-place compiler-rt installation, building from source offers explicit controls. For teams that only need the default WASI configuration, the release archive avoids maintaining their own LLVM and wasi-libc build procedure.

Editorial conclusion

wasi-sdk suits developers building C or C++ for WASI Preview 1, 2, or 3 who prefer a configured toolchain and sysroot. It is less suitable for projects that need an unlisted target or require shared-library, exception, thread, or LTO settings that must be reproduced from source. Verify first that the selected release contains the required target and that its `clang` can resolve the intended sysroot before adopting it as a build dependency.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. WebAssembly/wasi-sdk on GitHub