T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Remove references to wasm-bindgen in documentation (#5394)

Browse Source 
These references are really, really old and are no longer applicable. In
general the `wasm-*.md` documentation needs a lot of updates but this
applies at least a small band-aid to remove the `#[wasm_bindgen]`
references which are likely more harmful than helpful.
This commit is contained in:
Alex Crichton
2022-12-07 16:41:50 -06:00
committed by GitHub
parent 8c55b81300
commit c9527e0af6
1 changed files with 1 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
docs/wasm-rust.md
View File

@@ -131,107 +131,10 @@ While this works for some applications if you need to work with richer types
like strings or structs, then you'll want to use the support in `wasmtime` for like strings or structs, then you'll want to use the support in `wasmtime` for
interface types. interface types.
## WebAssembly Interface Types
> **Note**: support for interface types has temporarily removed from Wasmtime.
> This documentation is somewhat up to date but will no longer work with recent
> versions of Wasmtime. For more information see
> https://github.com/bytecodealliance/wasmtime/issues/677
Working with WebAssembly modules at the bare-bones level means that you're only
dealing with integers and floats. Many APIs, however, want to work with things
like byte arrays, strings, structures, etc. To facilitate these interactions the
[WebAssembly Interface Types
Proposal](https://github.com/webassembly/interface-types) comes into play. The
`wasmtime` runtime has support for interface types, and the Rust toolchain has
library support in a crate called
[`wasm-bindgen`](https://crates.io/crates/wasm-bindgen).
> **Note**: WebAssembly Interface Types is still a WebAssembly proposal and is
> under active development. The toolchain may not match the exact specification,
> and during development you'll generally need to make sure tool versions are
> all kept up to date to ensure everything aligns right. This'll all smooth over
> as the proposal stabilizes!
To get started with WebAssembly interface types let's write a library
module which will generate a greeting for us. The module itself won't do any
printing, we'll simply be working with some strings.
To get starts let's add this to our `Cargo.toml`:
```toml
[lib]
crate-type = ['cdylib']
[dependencies]
wasm-bindgen = "0.2.54"
```
Using this crate, we can then update our `src/lib.rs` with the following:
```rust,ignore
use wasm_bindgen::prelude::*;
#[wasm_bindgen]
pub fn greet(name: &str) -> String {
format!("Hello, {}!", name)
}
```
Then we can build this with:
```sh
$ cargo wasi build --release
Updating crates.io index
...
Finished dev [unoptimized + debuginfo] target(s) in 9.57s
Downloading precompiled wasm-bindgen v0.2.54
```
and we have our new wasm binary!
> **Note**: for now when using `wasm-bindgen` you must use `--release` mode to
> build wasi binaries with interface types.
We can then test out support for this with the CLI:
```sh
$ wasmtime --invoke greet ./target/wasm32-wasi/release/hello_world.wasm "Wasmtime CLI"
warning: using `--invoke` with a function that takes arguments is experimental and may break in the future
warning: using `--invoke` with a function that returns values is experimental and may break in the future
Hello, Wasmtime CLI!
```
Here we can see some experimental warnings, but we got our error message printed
out! The first CLI parameter, `"Wasmtime CLI"`, was passed as the first argument
of the `greet` function. The resulting string was then printed out to the
console.
Like before, we can also execute this with Python:
```sh
$ cp target/wasm32-wasi/release/hello_world.wasm .
$ python3
>>> import wasmtime
>>> import hello_world
>>> hello_world.greet('python interpreter')
'Hello, python interpreter!'
>>>
```
Note that `wasm-bindgen` was originally developed for JS and usage in a browser,
but a subset of its implementation (such as arguments which are strings) are
supported for WebAssembly interface types. You can also check out the [reference
documentation for `wasm-bindgen`](https://rustwasm.github.io/wasm-bindgen/) for
more information about how it works. Note that the `wasm-bindgen` support for
wasm interface type is still in its nascent phase and is likely to be greatly
improved in the future.
## Exporting Rust functionality ## Exporting Rust functionality
Currently only Rust functions can be exported from a wasm module. Rust functions Currently only Rust functions can be exported from a wasm module. Rust functions
must be `#[no_mangle]` to show up in the final binary, but if you're using must be `#[no_mangle]` to show up in the final binary.
`#[wasm_bindgen]` that will happen automatically for you.
Memory is by default exported from Rust modules under the name `memory`. This Memory is by default exported from Rust modules under the name `memory`. This
can be tweaked with the `-Clink-arg` flag to rustc to pass flags to LLD, the can be tweaked with the `-Clink-arg` flag to rustc to pass flags to LLD, the
@@ -273,19 +176,3 @@ extern "C" {
fn baz(); fn baz();
} }
``` ```
When you're using `wasm-bindgen` you would instead use:
```rust,ignore
use wasm_bindgen::prelude::*;
#[wasm_bindgen(module = "the-wasm-import-module")]
extern "C" {
fn foo();
fn baz();
// ...
}
```
Note that unless you're using interface types you likely don't need
`wasm-bindgen`.