Update README

README.md

@@ -14,74 +14,88 @@
   </p>
 </div>
 
-This crate contains API bindings for [WASI](https://github.com/WebAssembly/WASI)
-system calls in Rust, and currently reflects the `wasi_snapshot_preview1`
-module. This crate is quite low-level and provides conceptually a "system call"
-interface. In most settings, it's better to use the Rust standard library, which
-has WASI support.
+This crate contains bindings for [WASI](https://github.com/WebAssembly/WASI)
+APIs for the worlds:
 
-The `wasi` crate is also entirely procedurally generated from the `*.witx` files
-describing the WASI apis. While some conveniences are provided the bindings here
-are intentionally low-level!
+* [`wasi:cli/command`]
+* [`wasi:http/proxy`]
+
+This crate is procedurally generated from [WIT] files using [`wit-bindgen`].
+
+[`wasi:cli/command`]: https://github.com/WebAssembly/wasi-cli
+[`wasi:http/proxy`]: https://github.com/WebAssembly/wasi-http
+[WIT]: https://component-model.bytecodealliance.org/design/wit.html
+[`wit-bindgen`]: https://github.com/bytecodealliance/wit-bindgen
+[components]: https://component-model.bytecodealliance.org/
+[`wasm-tools`]: https://github.com/bytecodealliance/wasm-tools
 
 # Usage
 
 First you can depend on this crate via `Cargo.toml`:
 
 ```toml
 [dependencies]
-wasi = "0.8.0"
+wasi = "0.12.0"
 ```
 
 Next you can use the APIs in the root of the module like so:
 
 ```rust
 fn main() {
-    let stdout = 1;
-    let message = "Hello, World!\n";
-    let data = [wasi::Ciovec {
-        buf: message.as_ptr(),
-        buf_len: message.len(),
-    }];
-    wasi::fd_write(stdout, &data).unwrap();
+    let stdout = wasi::cli::stdout::get_stdout();
+    stdout.blocking_write_and_flush(b"Hello, world!\n").unwrap();
 }
 ```
 
-Next you can use a tool like [`cargo
-wasi`](https://github.com/bytecodealliance/cargo-wasi) to compile and run your
-project:
+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:
 
-To compile Rust projects to wasm using WASI, use the `wasm32-wasi` target,
-like this:
+```
+$ 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](https://github.com/bytecodealliance/wasmtime/releases/download/v17.0.0/wasi_snapshot_preview1.command.wasm).
 
 ```
-$ cargo wasi run
-   Compiling wasi v0.8.0+wasi-snapshot-preview1
-   Compiling wut v0.1.0 (/code)
-    Finished dev [unoptimized + debuginfo] target(s) in 0.34s
-     Running `/.cargo/bin/cargo-wasi target/wasm32-wasi/debug/wut.wasm`
-     Running `target/wasm32-wasi/debug/wut.wasm`
-Hello, World!
+$ curl -LO https://github.com/bytecodealliance/wasmtime/releases/download/v17.0.0/wasi_snapshot_preview1.command.wasm
 ```
 
-# Development
+Next to create a component you'll use the [`wasm-tools`] CLI to create a
+component:
 
-The bulk of the `wasi` crate is generated by the `witx-bindgen` tool, which lives at
-`crates/witx-bindgen` and is part of the cargo workspace.
+```
+$ cargo install wasm-tools
+$ wasm-tools component new target/wasm32-wasi/debug/foo.wasm \
+    --adapt ./wasi_snapshot_preview1.command.wasm \
+    -o component.wasm
+```
 
-The `src/lib_generated.rs` file can be re-generated with the following
-command:
+And finally the component can be run by a runtime that has Component Model
+support, such as [Wasmtime]:
 
 ```
-cargo run -p witx-bindgen -- crates/witx-bindgen/WASI/phases/snapshot/witx/wasi_snapshot_preview1.witx > src/lib_generated.rs
+$ wasmtime run component.wasm
+Hello, world!
 ```
 
-Note that this uses the WASI standard repository as a submodule. If you do not
-have this submodule present in your source tree, run:
+[Wasmtime]: https://github.com/bytecodealliance/wasmtime
+
+# Development
+
+The bulk of the `wasi` crate is generated by the [`wit-bindgen`] tool. The
+`src/bindings.rs` file can be regenerated with:
+
 ```
-git submodule update --init
+$ ./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.
+
 # License
 
 This project is licensed under the Apache 2.0 license with the LLVM exception.