1# Welcome to WASI! 2 3WASI stands for WebAssembly System Interface. It's an API designed by 4the [Wasmtime] project that provides access to several operating-system-like 5features, including files and filesystems, Berkeley sockets, clocks, and 6random numbers, that we'll be proposing for standardization. 7 8It's designed to be independent of browsers, so it doesn't depend on 9Web APIs or JS, and isn't limited by the need to be compatible with JS. 10And it has integrated capability-based security, so it extends 11WebAssembly's characteristic sandboxing to include I/O. 12 13See the [WASI Overview](WASI-overview.md) for more detailed background 14information, and the [WASI Tutorial](WASI-tutorial.md) for a walkthrough 15showing how various pieces fit together. 16 17Note that everything here is a prototype, and while a lot of stuff works, 18there are numerous missing features and some rough edges. One big thing 19that's not done yet is the actual mechanism to provide a directory as a 20pre-opened capability, to allow files to be opened. Some of the pieces 21are there (`__wasilibc_register_preopened_fd`) but they're not used yet. 22Networking support is also incomplete. 23 24## How can I write programs that use WASI? 25 26The two toolchains that currently work well are the Rust toolchain and 27a specially packaged C and C++ toolchain. Of course, we hope other 28toolchains will be able to implement WASI as well! 29 30### Rust 31 32To install a WASI-enabled Rust toolchain, follow the instructions here: 33 34https://github.com/alexcrichton/rust/releases/tag/wasi3 35 36Until now, Rust's WebAssembly support has had two main options, the 37Emscripten-based option, and the wasm32-unknown-unknown option. The latter 38option is lighter-weight, but only supports `no_std`. WASI enables a new 39wasm32-unknown-wasi target, which is similar to wasm32-unknown-unknown in 40that it doesn't depend on Emscripten, but it can use WASI to provide a 41decent subset of libstd. 42 43### C/C++ 44 45All the parts needed to support wasm are included in upstream clang, lld, and 46compiler-rt, as of the LLVM 8.0 release. However, to use it, you'll need 47to build WebAssembly-targeted versions of the library parts, and it can 48be tricky to get all the CMake invocations lined up properly. 49 50To make things easier, we provide 51[prebuilt packages](https://github.com/CraneStation/wasi-sdk/releases) 52that provide builds of Clang and sysroot libraries. 53 54Note that C++ support has a notable 55[bug](https://bugs.llvm.org/show_bug.cgi?id=40412) in clang which affects 56<iostream> in libcxx. This will be fixed in future versions. 57 58## How can I run programs that use WASI? 59 60Currently the options are [Wasmtime] and the [browser polyfill], though we 61intend WASI to be implementable in many wasm VMs. 62 63[Wasmtime]: https://github.com/CraneStation/wasmtime 64[browser polyfill]: https://wasi.dev/polyfill/ 65 66### Wasmtime 67 68[Wasmtime] is a non-Web WebAssembly engine which is part of the 69[CraneStation project](https://github.com/CraneStation/). To build 70it, download the code and build with `cargo build --release`. It can 71run WASI-using wasm programs by simply running `wasmtime foo.wasm`, 72or `cargo run --bin wasmtime foo.wasm`. 73 74### The browser polyfill 75 76The polyfill is online [here](https://wasi.dev/polyfill/). 77 78The source is [here](https://github.com/CraneStation/wasmtime-wasi/tree/wasi/lib/wasi/sandboxed-system-primitives/polyfill). 79 80## Where can I learn more? 81 82Beyond the [WASI Overview](WASI-overview.md), take a look at the 83various [WASI documents](WASI-documents.md). 84