diff --git a/README.md b/README.md index e9ab245..f00a953 100644 --- a/README.md +++ b/README.md @@ -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.