5c14d1eb6f
I thought it might be useful for future WASI users to have the WASI tutorial written not only in C but also in Rust. I'm also happy to keep the tutorial up to date with the current state of WASI target in Rust.
90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# Welcome to WASI!
|
|
|
|
WASI stands for WebAssembly System Interface. It's an API designed by
|
|
the [Wasmtime] project that provides access to several operating-system-like
|
|
features, including files and filesystems, Berkeley sockets, clocks, and
|
|
random numbers, that we'll be proposing for standardization.
|
|
|
|
It's designed to be independent of browsers, so it doesn't depend on
|
|
Web APIs or JS, and isn't limited by the need to be compatible with JS.
|
|
And it has integrated capability-based security, so it extends
|
|
WebAssembly's characteristic sandboxing to include I/O.
|
|
|
|
See the [WASI Overview](WASI-overview.md) for more detailed background
|
|
information, and the [WASI Tutorial](WASI-tutorial.md) for a walkthrough
|
|
showing how various pieces fit together, written in C. For Rust version,
|
|
see [rust-wasi-tutorial](https://github.com/kubkon/rust-wasi-tutorial).
|
|
|
|
Note that everything here is a prototype, and while a lot of stuff works,
|
|
there are numerous missing features and some rough edges. For example,
|
|
networking support is incomplete.
|
|
|
|
## How can I write programs that use WASI?
|
|
|
|
The two toolchains that currently work well are the Rust toolchain and
|
|
a specially packaged C and C++ toolchain. Of course, we hope other
|
|
toolchains will be able to implement WASI as well!
|
|
|
|
### Rust
|
|
|
|
To install a WASI-enabled Rust toolchain:
|
|
|
|
```
|
|
rustup target add wasm32-unknown-wasi --toolchain nightly
|
|
cargo +nightly build --target wasm32-unknown-wasi
|
|
```
|
|
|
|
Until now, Rust's WebAssembly support has had two main options, the
|
|
Emscripten-based option, and the wasm32-unknown-unknown option. The latter
|
|
option is lighter-weight, but only supports `no_std`. WASI enables a new
|
|
wasm32-unknown-wasi target, which is similar to wasm32-unknown-unknown in
|
|
that it doesn't depend on Emscripten, but it can use WASI to provide a
|
|
decent subset of libstd.
|
|
|
|
### C/C++
|
|
|
|
All the parts needed to support wasm are included in upstream clang, lld, and
|
|
compiler-rt, as of the LLVM 8.0 release. However, to use it, you'll need
|
|
to build WebAssembly-targeted versions of the library parts, and it can
|
|
be tricky to get all the CMake invocations lined up properly.
|
|
|
|
To make things easier, we provide
|
|
[prebuilt packages](https://github.com/CraneStation/wasi-sdk/releases)
|
|
that provide builds of Clang and sysroot libraries.
|
|
|
|
WASI doesn't yet support `setjmp`/`longjmp` or C++ exceptions, as it is
|
|
waiting for [unwinding support in WebAssembly].
|
|
|
|
[unwinding support in WebAssembly]: https://github.com/WebAssembly/exception-handling/
|
|
|
|
Some C++ programs, particularly those using `<iostream>`, may see warnings
|
|
about function signature mismatches; this is a
|
|
[known bug](https://bugs.llvm.org/show_bug.cgi?id=40412).
|
|
|
|
## How can I run programs that use WASI?
|
|
|
|
Currently the options are [Wasmtime] and the [browser polyfill], though we
|
|
intend WASI to be implementable in many wasm VMs.
|
|
|
|
[Wasmtime]: https://github.com/CraneStation/wasmtime
|
|
[browser polyfill]: https://wasi.dev/polyfill/
|
|
|
|
### Wasmtime
|
|
|
|
[Wasmtime] is a non-Web WebAssembly engine which is part of the
|
|
[CraneStation project](https://github.com/CraneStation/). To build
|
|
it, download the code and build with `cargo build --release`. It can
|
|
run WASI-using wasm programs by simply running `wasmtime foo.wasm`,
|
|
or `cargo run --bin wasmtime foo.wasm`.
|
|
|
|
### The browser polyfill
|
|
|
|
The polyfill is online [here](https://wasi.dev/polyfill/).
|
|
|
|
The source is [here](https://github.com/CraneStation/wasmtime/tree/master/wasmtime-wasi/js-polyfill).
|
|
|
|
## Where can I learn more?
|
|
|
|
Beyond the [WASI Overview](WASI-overview.md), take a look at the
|
|
various [WASI documents](WASI-documents.md).
|