Crates.io | wasi |
lib.rs | wasi |
version | 0.13.1+wasi-0.2.0 |
source | src |
created_at | 2019-03-27 16:47:22.126268 |
updated_at | 2024-05-20 16:08:33.076452 |
description | WASI API bindings for Rust |
homepage | |
repository | https://github.com/bytecodealliance/wasi-rs |
max_upload_size | |
id | 124199 |
size | 1,075,334 |
This crate contains bindings for WASI APIs for the worlds:
This crate is procedurally generated from WIT files using wit-bindgen
.
Depending on this crate can be done by adding it to your dependencies:
$ cargo add wasi
Next you can use the APIs in the root of the module like so:
fn main() {
let stdout = wasi::cli::stdout::get_stdout();
stdout.blocking_write_and_flush(b"Hello, world!\n").unwrap();
}
This crate is intended to target components but today you need to go through
the intermediate build step of a core WebAssembly module using the wasm32-wasi
target:
$ cargo build --target wasm32-wasi
Next you'll want an "adapter" to convert the Rust standard library's usage of
wasi_snapshot_preview1
to the component model. An example adapter can be found
from Wasmtime's release page.
$ curl -LO https://github.com/bytecodealliance/wasmtime/releases/download/v17.0.0/wasi_snapshot_preview1.command.wasm
Next to create a component you'll use the wasm-tools
CLI to create a
component:
$ cargo install wasm-tools
$ wasm-tools component new target/wasm32-wasi/debug/foo.wasm \
--adapt ./wasi_snapshot_preview1.command.wasm \
-o component.wasm
And finally the component can be run by a runtime that has Component Model support, such as Wasmtime:
$ wasmtime run component.wasm
Hello, world!
In January 2024 the WASI subgroup published WASI 0.2.0, colloquially known as "WASIp2". Around the same time the subgroup additionally decided to name the previous iteration of WASI as "WASIp1", historically known as "WASI preview1". This now-historical snapshot of WASI was defined with an entirely different set of primitives and worked very differently. This crate now targets WASIp2 and no longer targets WASIp1.
The last version of the wasi
crate to support WASIp1 was the
0.11.0+wasi-snapshot-preview1
version. This
version of the crate supported all WASIp1 APIs. WASIp1 was historically defined
with *.witx
files and used a bindings generator called witx-bindgen
.
This is a bit of a nuanced question/answer but the short answer is to probably
use the 0.11.0 release of wasi
for now if you're unsure.
The longer-form answer of this is that it depends on the Rust targets that you want to support. Rust WebAssembly targets include:
wasm32-unknown-unknown
- do not use this crate because this target indicates
that WASI is not desired.wasm32-wasi
or wasm32-wasip1
- this target has been present in Rust for
quite some time and is recently being renamed from wasm32-wasi
to
wasm32-wasip1
. The two targets have the same definition, it's just the name
that's changing. For this target you probably want the 0.11.0 track of this
crate.wasm32-wasip2
- this target is a recent addition to rustc (as of the time of
this writing it's not merged yet into rustc). This is what the 0.12.0 version
of the crate is intended for.Note that if you use wasm32-wasi
or wasm32-wasip1
it's not necessarily
guaranteed you want 0.11.0 of this crate. If your users are producing components
then you probably want 0.12.0 instead. If you don't know what your users are
producing then you should probably stick with 0.11.0.
Long story short, it's a bit complicated. We're in a transition period from WASIp1 to WASIp2 and things aren't going to be perfect every step of the way, so understanding is appreciated!
The bulk of the wasi
crate is generated by the wit-bindgen
tool. The
src/bindings.rs
file can be regenerated with:
$ ./ci/regenerate.sh
WASI definitions are located in the wit
directory of this repository.
Currently they're copied from upstream repositories but are hoped to be better
managed in the future.
This project is triple licenced under the Apache 2/ Apache 2 with LLVM exceptions/ MIT licences. The reasoning for this is:
For more details see
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache 2/ Apache 2 with LLVM exceptions/ MIT licenses, shall be licensed as above, without any additional terms or conditions.