| 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. |