diff --git a/README.md b/README.md index 1f747e1b..7a01cb2d 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,23 @@ # wasm-bindgen -A CLI and Rust dependency for generating JS bindings of an interface defined in -Rust (and maybe eventually other languages!) +A CLI and Rust dependency for acting as a polyfill for [Wasm host +bindings][host], allowing you to interoperate with JS from wasm with types like +strings, JS objects, etc. + +[host]: https://github.com/WebAssembly/host-bindings [](https://travis-ci.org/alexcrichton/wasm-bindgen) [](https://ci.appveyor.com/project/alexcrichton/wasm-bindgen) -This project is intended to be a framework for interoperating between JS and -Rust. Currently it's very Rust-focused but it's hoped that one day the -`wasm-bindgen-cli` tool will not be so Rust-specific and would be amenable to -bindgen for C/C++ modules. +This project is a "temporary" polyfill for the [host bindings proposal][host] +which is intended to empower wasm modules to interact with host objects such as +strings, JS objects, etc. This project enables defining JS classes in wasm, +taking strings from JS in wasm, and calling into JS with JS objects previously +provided. + +Currently this tool is Rust-focused but the underlying foundation is +language-independent, and it's hoping that over time as this tool stabilizes +that it can be used for languages like C/C++! Notable features of this project includes: @@ -104,30 +112,49 @@ set of JS bindings as well. Let's invoke it! ``` $ wasm-bindgen target/wasm32-unknown-unknown/release/js_hello_world.wasm \ - --output-ts hello.ts \ - --output-wasm hello.wasm + --out-dir . ``` -This'll create a `hello.ts` (a TypeScript file) which binds the functions -described in `js_hello_world.wasm`, and the `hello.wasm` will be a little -smaller than the input `js_hello_world.wasm`, but it's otherwise equivalent. -Note that `hello.ts` isn't very pretty so to read it you'll probably want to run -it through a formatter. +This is the main point where the magic happens. The `js_hello_world.wasm` file +emitted by rustc contains *descriptors* of how to communicate via richer types +than wasm currently supports. The `wasm-bindgen` tool will interpret this +information, emitting a **replacement module** for the wasm file. -Typically you'll be feeding this typescript into a larger build system, and -often you'll be using this with your own typescript project as well. For now -though we'll just want the JS output, so let's convert it real quick: +The previous `js_hello_world.wasm` file is interpreted as if it were an ES6 +module. The `js_hello_world.js` file emitted by `wasm-bindgen` should have the +intended interface of the wasm file, notably with rich types like strings, +classes, etc. -``` -$ npm install typescript @types/webassembly-js-api @types/text-encoding -$ ./node_modules/typescript/bin/tsc hello.ts --lib es6 -m es2015 +The `wasm-bindgen` tool also emits a secondary file, `js_hello_world_wasm.wasm`. +This is the original wasm file but postprocessed a bit. It's intended that the +`js_hello_world_wasm.wasm` file, like before, acts like an ES6 module. The +`js_hello_world.wasm` file, for example, uses `import` to import functionality +from the wasm. + +Note that you can also pass a `--nodejs` argument to `wasm-bindgen` for emitting +Node-compatible JS as well as a `--typescript` argument to emit a `*.d.ts` file +describing the exported contents. + +At this point you'll typically plug these files into a larger build system. Both +files emitted by `wasm-bindgen` act like normal ES6 modules (one just happens to +be wasm). As of the time of this writing there's unfortunately not a lot of +tools that natively do this (but they're coming!). In the meantime we can use +the `wasm2es6js` utility (aka "hack") from the `wasm-bindgen` tool we previously +installed along with the `parcel-bundler` packager. Note that these steps will +differ depending on your build system. + +Alright first create an `index.js` file: + +```js +import { greet } from "./js_hello_world"; +import { booted } from "./js_hello_world_wasm"; + +booted.then(() => { + alert(greet("World!")) +}); ``` -Below we'll be using ES6 modules, but your browser may not support them natively -just yet. To see more information about this, you can browse -[online](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import). - -Ok let's see what this look like on the web! +Then a corresponding `index.html`: ```html @@ -135,27 +162,22 @@ Ok let's see what this look like on the web!
- +