Debian Codegraph @

.cargo/vendor/wasm-bindgen/guide/src/contributing/design/index.md

raw
1 # Design of `wasm-bindgen`
2
3 This section is intended to be a deep-dive into how `wasm-bindgen` internally
4 works today, specifically for Rust. If you're reading this far in the future it
5 may no longer be up to date, but feel free to open an issue and we can try to
6 answer questions and/or update this!
7
8 ## Foundation: ES Modules
9
10 The first thing to know about `wasm-bindgen` is that it's fundamentally built on
11 the idea of ES Modules. In other words this tool takes an opinionated stance
12 that wasm files *should be viewed as ES modules*. This means that you can
13 `import` from a wasm file, use its `export`-ed functionality, etc, from normal
14 JS files.
15
16 Now unfortunately at the time of this writing the interface of wasm interop
17 isn't very rich. Wasm modules can only call functions or export functions that
18 deal exclusively with `i32`, `i64`, `f32`, and `f64`. Bummer!
19
20 That's where this project comes in. The goal of `wasm-bindgen` is to enhance the
21 "ABI" of wasm modules with richer types like classes, JS objects, Rust structs,
22 strings, etc. Keep in mind, though, that everything is based on ES Modules! This
23 means that the compiler is actually producing a "broken" wasm file of sorts. The
24 wasm file emitted by rustc, for example, does not have the interface we would
25 like to have. Instead it requires the `wasm-bindgen` tool to postprocess the
26 file, generating a `foo.js` and `foo_bg.wasm` file. The `foo.js` file is the
27 desired interface expressed in JS (classes, types, strings, etc) and the
28 `foo_bg.wasm` module is simply used as an implementation detail (it was
29 lightly modified from the original `foo.wasm` file).
30
31 As more features are stabilized in WebAssembly over time (like component model)
32 the JS file is expected to get smaller and smaller. It's unlikely to ever
33 disappear, but `wasm-bindgen` is designed to follow the WebAssembly spec and
34 proposals closely to optimize JS/Rust as much as possible.
35
36 ## Foundation #2: Unintrusive in Rust
37
38 On the more Rust-y side of things the `wasm-bindgen` crate is designed to
39 ideally have as minimal impact on a Rust crate as possible. Ideally a few
40 `#[wasm_bindgen]` attributes are annotated in key locations and otherwise you're
41 off to the races. The attribute strives to both not invent new syntax and work
42 with existing idioms today.
43
44 For example a library might exposed a function in normal Rust that looks like:
45
46 ```rust
47 pub fn greet(name: &str) -> String {
48 // ...
49 }
50 ```
51
52 And with `#[wasm_bindgen]` all you need to do in exporting it to JS is:
53
54 ```rust
55 #[wasm_bindgen]
56 pub fn greet(name: &str) -> String {
57 // ...
58 }
59 ```
60
61 Additionally the design here with minimal intervention in Rust should allow us
62 to easily take advantage of the upcoming [component model][component-model] proposal. Ideally
63 you'd simply upgrade `wasm-bindgen`-the-crate as well as your toolchain and
64 you're immediately getting raw access to component model! (this is still a bit of
65 a ways off though...)
66
67 [component-model]: https://github.com/WebAssembly/component-model