msb_14154
/
wasi-sdk
mirror of https://github.com/WebAssembly/wasi-sdk
1
0
Code Issues Projects Releases Wiki Activity

Improve `README.md` (#331)

Browse Source 
This changes the front-page documentation to:
- use out-of-line links in more places
- mention the need for `libclang_rt.builtins-wasm32.a` when using
  standard Clang
- mention how to use a `wasi-libc` sysroot
- explain the experimental status of `wasm32-wasi-threads
pull/169/head
Andrew Brown 2 years ago committed by GitHub
parent 9a271da937
commit 00cb3b2e5f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 40 additions and 28 deletions
Show Stats Download Patch File Download Diff File

68
README.md
Unescape View File

@ -2,7 +2,9 @@
## Quick Start ## 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 ## 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 git submodules to pull in the upstream Clang and LLVM tree, as well as the
wasi-libc tree. wasi-libc tree.
The libc portion of this SDK is the The libc portion of this SDK is maintained in [wasi-libc].
[wasi-libc](https://github.com/WebAssembly/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, 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 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. convenience.
One could also use a standard Clang installation, build a sysroot from the One could also use a standard Clang installation, build a sysroot from the
sources mentioned above, and compile with sources mentioned above, and compile with `--target=wasm32-wasi
"--target=wasm32-wasi --sysroot=/path/to/sysroot". --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 ## 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: A typical installation from the release binaries might look like the following:
```shell script ```shell script
export WASI_VERSION=14 export WASI_VERSION=20
export WASI_VERSION_FULL=${WASI_VERSION}.0 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 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 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 Note: `${WASI_SDK_PATH}/share/wasi-sysroot` contains the WASI-specific
includes/libraries/etc. The `--sysroot=...` option is not necessary if 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 ## Notes for Autoconf
[Autoconf](https://www.gnu.org/software/autoconf/autoconf.html) 2.70 now [Autoconf] 2.70 now [recognizes WASI].
[recognizes WASI](https://git.savannah.gnu.org/gitweb/?p=autoconf.git;a=blob;f=build-aux/config.sub;h=19c9553b1825cafb182115513bc628e0ee801bd0;hb=97fbc5c184acc6fa591ad094eae86917f03459fa#l1723).
[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 For convenience when building packages that aren't yet updated, updated
config.sub and config.guess files are installed at `share/misc/config.*` config.sub and config.guess files are installed at `share/misc/config.*`
@ -88,11 +97,12 @@ in the install directory.
## Docker Image ## Docker Image
We provide a [docker image](https://github.com/WebAssembly/wasi-sdk/pkgs/container/wasi-sdk) We provide a [docker image] including wasi-sdk that can be used for building
including wasi-sdk that can be used for building projects without a projects without a separate installation of the SDK. Autotools, CMake, and Ninja
separate installation of the SDK. Autotools, CMake, and Ninja are included are included in this image, and standard environment variables are set to use
in this image, and standard environment variables are set to use wask-sdk wask-sdk for building.
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 For example, this command can build a make-based project with the Docker
image. image.
@ -107,24 +117,26 @@ disabled in a configure step before building with wasi-sdk.
## Notable Limitations ## Notable Limitations
This repository does not yet support C++ exceptions. C++ code is This repository does not yet support __C++ exceptions__. C++ code is supported
supported only with -fno-exceptions for now. Similarly, there is not only with -fno-exceptions for now. Similarly, there is not yet support for
yet support for setjmp/longjmp. Work on support for [exception handling] setjmp/longjmp. Work on support for [exception handling] is underway at the
is underway at the language level which will support both of these language level which will support both of these features.
features.
[exception handling]: https://github.com/WebAssembly/exception-handling/ [exception handling]: https://github.com/WebAssembly/exception-handling/
This repository does not yet support [threads]. Specifically, WASI does This repository experimentally supports __threads__ with
not yet have an API for creating and managing threads yet, and WASI libc `--target=wasm32-wasi-threads`. It uses WebAssembly's [threads] primitives
does not yet have pthread support. (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 [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
[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.
There is no support for networking. It is a goal of WASI to support networking There is no support for __networking__. It is a goal of WASI to support
in the future though. networking in the future though.

Write Preview
Loading…
Cancel
Save