]>
Commit | Line | Data |
---|---|---|
064997fb FG |
1 | <div align="center"> |
2 | <h1><code>wasi</code></h1> | |
3 | ||
4 | <strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong> | |
5 | ||
6 | <p> | |
7 | <strong>WASI API Bindings for Rust</strong> | |
8 | </p> | |
9 | ||
10 | <p> | |
11 | <a href="https://crates.io/crates/wasi"><img src="https://img.shields.io/crates/v/wasi.svg?style=flat-square" alt="Crates.io version" /></a> | |
12 | <a href="https://crates.io/crates/wasi"><img src="https://img.shields.io/crates/d/wasi.svg?style=flat-square" alt="Download" /></a> | |
13 | <a href="https://docs.rs/wasi/"><img src="https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square" alt="docs.rs docs" /></a> | |
14 | </p> | |
15 | </div> | |
16 | ||
17 | This crate contains API bindings for [WASI](https://github.com/WebAssembly/WASI) | |
18 | system calls in Rust, and currently reflects the `wasi_snapshot_preview1` | |
19 | module. This crate is quite low-level and provides conceptually a "system call" | |
20 | interface. In most settings, it's better to use the Rust standard library, which | |
21 | has WASI support. | |
22 | ||
23 | The `wasi` crate is also entirely procedurally generated from the `*.witx` files | |
24 | describing the WASI apis. While some conveniences are provided the bindings here | |
25 | are intentionally low-level! | |
26 | ||
27 | # Usage | |
28 | ||
29 | First you can depend on this crate via `Cargo.toml`: | |
30 | ||
31 | ```toml | |
32 | [dependencies] | |
33 | wasi = "0.8.0" | |
34 | ``` | |
35 | ||
36 | Next you can use the APIs in the root of the module like so: | |
37 | ||
38 | ```rust | |
39 | fn main() { | |
40 | let stdout = 1; | |
41 | let message = "Hello, World!\n"; | |
42 | let data = [wasi::Ciovec { | |
43 | buf: message.as_ptr(), | |
44 | buf_len: message.len(), | |
45 | }]; | |
46 | wasi::fd_write(stdout, &data).unwrap(); | |
47 | } | |
48 | ``` | |
49 | ||
50 | Next you can use a tool like [`cargo | |
51 | wasi`](https://github.com/bytecodealliance/cargo-wasi) to compile and run your | |
52 | project: | |
53 | ||
54 | To compile Rust projects to wasm using WASI, use the `wasm32-wasi` target, | |
55 | like this: | |
56 | ||
57 | ``` | |
58 | $ cargo wasi run | |
59 | Compiling wasi v0.8.0+wasi-snapshot-preview1 | |
60 | Compiling wut v0.1.0 (/code) | |
61 | Finished dev [unoptimized + debuginfo] target(s) in 0.34s | |
62 | Running `/.cargo/bin/cargo-wasi target/wasm32-wasi/debug/wut.wasm` | |
63 | Running `target/wasm32-wasi/debug/wut.wasm` | |
64 | Hello, World! | |
65 | ``` | |
66 | ||
67 | # Development | |
68 | ||
69 | The bulk of the `wasi` crate is generated by the `witx-bindgen` tool, which lives at | |
70 | `crates/witx-bindgen` and is part of the cargo workspace. | |
71 | ||
72 | The `src/lib_generated.rs` file can be re-generated with the following | |
73 | command: | |
74 | ||
75 | ``` | |
76 | cargo run -p witx-bindgen -- crates/witx-bindgen/WASI/phases/snapshot/witx/wasi_snapshot_preview1.witx > src/lib_generated.rs | |
77 | ``` | |
78 | ||
79 | Note that this uses the WASI standard repository as a submodule. If you do not | |
80 | have this submodule present in your source tree, run: | |
81 | ``` | |
82 | git submodule update --init | |
83 | ``` | |
84 | ||
85 | # License | |
86 | ||
87 | This project is licensed under the Apache 2.0 license with the LLVM exception. | |
88 | See [LICENSE](LICENSE) for more details. | |
89 | ||
90 | ### Contribution | |
91 | ||
92 | Unless you explicitly state otherwise, any contribution intentionally submitted | |
93 | for inclusion in this project by you, as defined in the Apache-2.0 license, | |
94 | shall be licensed as above, without any additional terms or conditions. |