@ -2,7 +2,9 @@
## Quick Start
[Download SDK packages here. ](https://github.com/WebAssembly/wasi-sdk/releases )
[Download SDK packages here.][releases]
[releases]: https://github.com/WebAssembly/wasi-sdk/releases
## About this repository
@ -10,8 +12,9 @@ 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 the
[wasi-libc ](https://github.com/WebAssembly/wasi-libc ).
The libc portion of this SDK is maintained in [wasi-libc].
[wasi-libc]: https://github.com/WebAssembly/wasi-libc
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
@ -19,8 +22,11 @@ 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-wasi --sysroot=/path/to/sysroot".
sources mentioned above, and compile with `--target=wasm32-wasi
--sysroot=/path/to/sysroot`. In this scenario, one would also need the
`libclang_rt.builtins-wasm32.a` objects available separately in the [release
downloads][releases] which must be extracted into
`$CLANG_INSTALL_DIR/$CLANG_VERSION/lib/wasi/` .
## Clone
@ -57,7 +63,7 @@ version of the package on GitHub, see [RELEASING.md](RELEASING.md).
A typical installation from the release binaries might look like the following:
```shell script
export WASI_VERSION=14
export WASI_VERSION=20
export WASI_VERSION_FULL=${WASI_VERSION}.0
wget https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-${WASI_VERSION}/wasi-sdk-${WASI_VERSION_FULL}-linux.tar.gz
tar xvf wasi-sdk-${WASI_VERSION_FULL}-linux.tar.gz
@ -75,12 +81,15 @@ $CC foo.c -o foo.wasm
Note: `${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` .
`WASI_SDK_PATH` is `/opt/wasi-sdk` . For troubleshooting, one can replace the
`--sysroot` path with a manual build of [wasi-libc].
## Notes for Autoconf
[Autoconf ](https://www.gnu.org/software/autoconf/autoconf.html ) 2.70 now
[recognizes WASI ](https://git.savannah.gnu.org/gitweb/?p=autoconf.git;a=blob;f=build-aux/config.sub;h=19c9553b1825cafb182115513bc628e0ee801bd0;hb=97fbc5c184acc6fa591ad094eae86917f03459fa#l1723 ).
[Autoconf] 2.70 now [recognizes WASI].
[Autoconf]: https://www.gnu.org/software/autoconf/autoconf.html
[recognizes WASI]: https://git.savannah.gnu.org/gitweb/?p=autoconf.git;a=blob;f=build-aux/config.sub;h=19c9553b1825cafb182115513bc628e0ee801bd0;hb=97fbc5c184acc6fa591ad094eae86917f03459fa#l1723
For convenience when building packages that aren't yet updated, updated
config.sub and config.guess files are installed at `share/misc/config.*`
@ -88,11 +97,12 @@ in the install directory.
## Docker Image
We provide a [docker image ](https://github.com/WebAssembly/wasi-sdk/pkgs/container/wasi-sdk )
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 wask-sdk
for building.
We provide a [docker image] 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
wask-sdk for building.
[docker image]: https://github.com/WebAssembly/wasi-sdk/pkgs/container/wasi-sdk
For example, this command can build a make-based project with the Docker
image.
@ -107,24 +117,26 @@ disabled in a configure step before building with wasi-sdk.
## Notable Limitations
This repository does not yet support C++ exceptions. C++ code is
supported only with -fno-exceptions for now. Similarly, there is not
yet support for setjmp/longjmp. Work on support for [exception handling]
is underway at the language level which will support both of these
features.
This repository does not yet support __C++ exceptions__ . C++ code is supported
only with -fno-exceptions for now. Similarly, there is not yet support for
setjmp/longjmp. Work on support for [exception handling] is underway at the
language level which will support both of these features.
[exception handling]: https://github.com/WebAssembly/exception-handling/
This repository does not yet support [threads]. Specifically, WASI does
not yet have an API for creating and managing threads yet, and WASI libc
does not yet have pthread support.
This repository experimentally supports __threads__ with
`--target=wasm32-wasi-threads` . It uses WebAssembly's [threads] primitives
(atomics, `wait` /`notify`, shared memory) and [wasi-threads] for spawning
threads. Note: this is experimental — do not expect long-term stability!
[threads]: https://github.com/WebAssembly/threads
[wasi-threads]: https://github.com/WebAssembly/wasi-threads
This repository does not yet support __dynamic libraries__ . While there are
[some efforts] to design a system for dynamic libraries in wasm, it is still in
development and not yet generally usable.
This repository does not yet support dynamic libraries. While there are
[some efforts ](https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md )
to design a system for dynamic libraries in wasm, it is still in development
and not yet generally usable.
[some efforts]: https://github.com/WebAssembly/tool-conventions/blob/master/DynamicLinking.md
There is no support for networking. It is a goal of WASI to support networking
in the future though.
There is no support for __networking__ . It is a goal of WASI to support
networking in the future though.