Debian Codegraph @

.cargo/vendor/wasip2/README.md

raw
1 <div align="center">
2 <h1><code>wasip2</code></h1>
3
4 <strong>A <a href="https://bytecodealliance.org/">Bytecode Alliance</a> project</strong>
5
6 <p>
7 <strong>WASIp2 API Bindings for Rust</strong>
8 </p>
9
10 <p>
11 <a href="https://crates.io/crates/wasip2"><img src="https://img.shields.io/crates/v/wasip2.svg?style=flat-square" alt="Crates.io version" /></a>
12 <a href="https://crates.io/crates/wasip2"><img src="https://img.shields.io/crates/d/wasip2.svg?style=flat-square" alt="Download" /></a>
13 <a href="https://docs.rs/wasip2/"><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 bindings for [WASIp2](https://github.com/WebAssembly/WASI)
18 APIs for the worlds:
19
20 * [`wasi:cli/command`]
21 * [`wasi:http/proxy`]
22
23 This crate is procedurally generated from [WIT] files using [`wit-bindgen`].
24
25 [`wasi:cli/command`]: https://github.com/WebAssembly/wasi-cli
26 [`wasi:http/proxy`]: https://github.com/WebAssembly/wasi-http
27 [WIT]: https://component-model.bytecodealliance.org/design/wit.html
28 [`wit-bindgen`]: https://github.com/bytecodealliance/wit-bindgen
29 [components]: https://component-model.bytecodealliance.org/
30 [`wasm-tools`]: https://github.com/bytecodealliance/wasm-tools
31
32 # Usage
33
34 Depending on this crate can be done by adding it to your dependencies:
35
36 ```sh
37 $ cargo add wasip2
38 ```
39
40 Next you can use the APIs in the root of the module like so:
41
42 ```rust
43 fn main() {
44 let stdout = wasip2::cli::stdout::get_stdout();
45 stdout.blocking_write_and_flush(b"Hello, world!\n").unwrap();
46 }
47 ```
48
49 This crate can currently be used in three main ways.
50
51 - One is to use it and compile for the [`wasm32-wasip2` target] in Rust 1.82 and later.
52 this is the simplest approach, as all the tools needed are included in the
53 Rust tooling, however it doesn't yet support some of the features of the
54 other approaches.
55
56 - Another is to use it and compile using [`cargo component`]. This is essentially
57 the same as the next option, except that `cargo component` handles most of the
58 steps for you. `cargo component` also has a number of additional features for
59 working with dependencies and custom WIT interfaces.
60
61 - And the third is to compile for the `wasm32-wasip1` target, and then adapt
62 the resulting modules into component using `wasm-tools component new`; see
63 the next section here for details.
64
65 [`wasm32-wasip2` target]: https://blog.rust-lang.org/2024/11/26/wasip2-tier-2.html
66 [`cargo component`]: https://github.com/bytecodealliance/cargo-component
67
68 ## Building with wasm32-wasip1 and `cargo component new`.
69
70 The `wasm32-wasip2` target works with a simple `cargo build --target wasm32-wasip2`
71 and doesn't need a lot of documentation here, and `cargo component` has its own
72 documentation, so here we have some documentation for the `wasm32-wasip1` way.
73
74 ```
75 $ cargo build --target wasm32-wasip1
76 ```
77
78 Next you'll want an "adapter" to convert the Rust standard library's usage of
79 `wasi_snapshot_preview1` to the component model. An example adapter can be found
80 from [Wasmtime's release page](https://github.com/bytecodealliance/wasmtime/releases/download/v17.0.0/wasi_snapshot_preview1.command.wasm).
81
82 ```
83 $ curl -LO https://github.com/bytecodealliance/wasmtime/releases/download/v17.0.0/wasi_snapshot_preview1.command.wasm
84 ```
85
86 Next to create a component you'll use the [`wasm-tools`] CLI to create a
87 component:
88
89 ```
90 $ cargo install wasm-tools
91 $ wasm-tools component new target/wasm32-wasip1/debug/foo.wasm \
92 --adapt ./wasi_snapshot_preview1.command.wasm \
93 -o component.wasm
94 ```
95
96 And finally the component can be run by a runtime that has Component Model
97 support, such as [Wasmtime]:
98
99 ```
100 $ wasmtime run component.wasm
101 Hello, world!
102 ```
103
104 [Wasmtime]: https://github.com/bytecodealliance/wasmtime
105
106 # Development
107
108 The bulk of the `wasip2` crate is generated by the [`wit-bindgen`] tool. The
109 `src/bindings.rs` file can be regenerated with:
110
111 ```
112 $ ./ci/regenerate.sh
113 ```
114
115 WASI definitions are located in the `wit` directory of this repository.
116 Currently they're copied from upstream repositories but are hoped to be better
117 managed in the future.