2018-06-19 21:10:41 +03:00
|
|
|
<meta charset="utf-8"/>
|
2017-12-19 01:49:04 +03:00
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
# `wasm-bindgen`
|
2018-01-30 08:20:38 +03:00
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
**Facilitating high-level interactions between wasm modules and JavaScript.**
|
|
|
|
|
2019-03-02 06:54:36 +03:00
|
|
|
[![Build Status](https://dev.azure.com/rustwasm/wasm-bindgen/_apis/build/status/rustwasm.wasm-bindgen?branchName=master)](https://dev.azure.com/rustwasm/wasm-bindgen/_build/latest?definitionId=1&branchName=master)
|
2018-10-04 20:45:00 +03:00
|
|
|
[![](https://meritbadge.herokuapp.com/wasm-bindgen)](https://crates.io/crates/wasm-bindgen)
|
2018-06-19 21:10:41 +03:00
|
|
|
[![](https://img.shields.io/crates/d/wasm-bindgen.svg)](https://crates.io/crates/wasm-bindgen)
|
|
|
|
[![API Documentation on docs.rs](https://docs.rs/wasm-bindgen/badge.svg)](https://docs.rs/wasm-bindgen)
|
2017-12-19 01:49:04 +03:00
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
Import JavaScript things into Rust and export Rust things to JavaScript.
|
2017-12-19 03:35:36 +03:00
|
|
|
|
|
|
|
```rust
|
|
|
|
extern crate wasm_bindgen;
|
|
|
|
use wasm_bindgen::prelude::*;
|
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
// Import the `window.alert` function from the Web.
|
2018-02-08 03:41:33 +03:00
|
|
|
#[wasm_bindgen]
|
2018-11-27 23:27:00 +03:00
|
|
|
extern "C" {
|
2018-02-08 03:41:33 +03:00
|
|
|
fn alert(s: &str);
|
|
|
|
}
|
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
// Export a `greet` function from Rust to JavaScript, that alerts a
|
|
|
|
// hello message.
|
2018-02-08 03:41:33 +03:00
|
|
|
#[wasm_bindgen]
|
2018-03-06 01:25:15 +03:00
|
|
|
pub fn greet(name: &str) {
|
2018-02-08 03:41:33 +03:00
|
|
|
alert(&format!("Hello, {}!", name));
|
2017-12-19 03:35:36 +03:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
2018-08-02 02:42:23 +03:00
|
|
|
Use exported Rust things from JavaScript with ECMAScript modules!
|
2018-01-30 08:20:38 +03:00
|
|
|
|
|
|
|
```js
|
2018-08-02 02:42:23 +03:00
|
|
|
import { greet } from "./hello_world";
|
|
|
|
|
|
|
|
greet("World!");
|
2017-12-20 06:06:48 +03:00
|
|
|
```
|
2017-12-19 03:35:36 +03:00
|
|
|
|
2018-08-30 00:23:20 +03:00
|
|
|
## Features
|
|
|
|
|
|
|
|
* **Lightweight.** Only pay for what you use. `wasm-bindgen` only generates
|
|
|
|
bindings and glue for the JavaScript imports you actually use and Rust
|
|
|
|
functionality that you export. For example, importing and using the
|
|
|
|
`document.querySelector` method doesn't cause `Node.prototype.appendChild` or
|
|
|
|
`window.alert` to be included in the bindings as well.
|
|
|
|
|
|
|
|
* **ECMAScript modules.** Just import WebAssembly modules the same way you would
|
|
|
|
import JavaScript modules. Future compatible with [WebAssembly modules and
|
|
|
|
ECMAScript modules integration][wasm-es-modules].
|
|
|
|
|
|
|
|
* **Designed with the ["host bindings" proposal][host-bindings] in mind.**
|
|
|
|
Eventually, there won't be any JavaScript shims between Rust-generated wasm
|
|
|
|
functions and native DOM methods. Because the wasm functions are statically
|
|
|
|
type checked, some of those native methods' dynamic type checks should become
|
|
|
|
unnecessary, promising to unlock even-faster-than-JavaScript DOM access.
|
|
|
|
|
|
|
|
[wasm-es-modules]: https://github.com/WebAssembly/esm-integration
|
|
|
|
[host-bindings]: https://github.com/WebAssembly/host-bindings/blob/master/proposals/host-bindings/Overview.md
|
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
## Guide
|
2018-03-03 07:11:30 +03:00
|
|
|
|
2018-09-06 01:00:08 +03:00
|
|
|
[**📚 Read the `wasm-bindgen` guide here! 📚**](https://rustwasm.github.io/wasm-bindgen)
|
2018-03-03 07:19:39 +03:00
|
|
|
|
2018-09-16 15:12:48 +03:00
|
|
|
## API Docs
|
|
|
|
|
|
|
|
- [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen/)
|
2018-09-16 15:19:18 +03:00
|
|
|
- [js-sys](https://rustwasm.github.io/wasm-bindgen/api/js_sys/)
|
|
|
|
- [web-sys](https://rustwasm.github.io/wasm-bindgen/api/web_sys/)
|
2018-09-16 15:12:48 +03:00
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
## License
|
2017-12-19 01:49:04 +03:00
|
|
|
|
|
|
|
This project is licensed under either of
|
|
|
|
|
|
|
|
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0)
|
|
|
|
* MIT license ([LICENSE-MIT](LICENSE-MIT) or
|
|
|
|
http://opensource.org/licenses/MIT)
|
|
|
|
|
|
|
|
at your option.
|
|
|
|
|
2018-06-19 21:10:41 +03:00
|
|
|
## Contribution
|
|
|
|
|
2018-06-19 21:49:34 +03:00
|
|
|
**[See the "Contributing" section of the guide for information on
|
|
|
|
hacking on `wasm-bindgen`!][contributing]**
|
2017-12-19 01:49:04 +03:00
|
|
|
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
|
|
for inclusion in this project by you, as defined in the Apache-2.0 license,
|
|
|
|
shall be dual licensed as above, without any additional terms or conditions.
|
2018-02-23 16:52:45 +03:00
|
|
|
|
2018-10-05 18:25:55 +03:00
|
|
|
[contributing]: https://rustwasm.github.io/wasm-bindgen/contributing/index.html
|