rustwasm/wasm-bindgen
1
0
Fork 0
mirror of https://github.com/rustwasm/wasm-bindgen.git synced 2024-12-15 12:44:31 +03:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
36c0a1347d
wasm-bindgen/README.md

96 lines
3.4 KiB
Markdown
Raw Normal View History

Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
<meta charset="utf-8"/>
Add CI and a small README
2017-12-19 01:49:04 +03:00
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
# `wasm-bindgen`
Rewrite wasm-bindgen with ES6 modules in mind This commit is a mostly-rewrite of the `wasm-bindgen` tool. After some recent discussions it's clear that the previous model wasn't quite going to cut it, and this iteration is one which primarily embraces ES6 modules and the idea that this is a polyfill for host bindings. The overall interface and functionality hasn't changed much but the underlying technology has now changed significantly. Previously `wasm-bindgen` would emit a JS file that acted as an ES6 module but had a bit of a wonky interface. It exposed an async function for instantiation of the wasm module, but that's the bundler's job, not ours! Instead this iteration views each input and output as a discrete ES6 module. The input wasm file is interpreted as "this *should* be an ES6 module with rich types" and the output is "well here's some ES6 modules that fulfill that contract". Notably the tool now replaces the original wasm ES6 module with a JS ES6 module that has the "rich interface". Additionally a second ES6 module is emitted (the actual wasm file) which imports and exports to the original ES6 module. This strategy is hoped to be much more amenable to bundlers and controlling how the wasm itself is instantiated. The emitted files files purely assume ES6 modules and should be able to work as-is once ES6 module integration for wasm is completed. Note that there aren't a ton of tools to pretend a wasm module is an ES6 module at the moment but those should be coming soon! In the meantime a local `wasm2es6js` hack was added to help make *something* work today. The README has also been updated with instructions for interacting with this model.
2018-01-30 08:20:38 +03:00
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
**Facilitating high-level interactions between wasm modules and JavaScript.**
Add build badge for Azure Pipelines
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)
Use `https` on badge url
2018-10-04 20:45:00 +03:00
[![](https://meritbadge.herokuapp.com/wasm-bindgen)](https://crates.io/crates/wasm-bindgen)
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
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)
Add CI and a small README
2017-12-19 01:49:04 +03:00
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
Import JavaScript things into Rust and export Rust things to JavaScript.
Add a basic README which at least attempts
2017-12-19 03:35:36 +03:00
```rust
extern crate wasm_bindgen;
use wasm_bindgen::prelude::*;
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
// Import the `window.alert` function from the Web.
Migrate from a macro to an attribute This commit migrates from `wasm_bindgen!`-the-macro to `#[wasm_bindgen]`-the-attribute. The actual mechanics of the macro are relatively simple in just generating some shims here and there, but wrapping everything in one huge macro invocation can often seem intimidating as it gives off this feeling of "oh dear anything can happen here!" Using an attribute should curb expectations much more greatly of "oh there's just some extra stuff happening behind the scenes". The usage is otherwise relatively straightforward and close to what it was before, but check out the DESIGN.md/README.md changes for more info!
2018-02-08 03:41:33 +03:00
#[wasm_bindgen]
Consistently use `extern "C"` This is what rustfmt favors, so let's favor it too! Closes #1042
2018-11-27 23:27:00 +03:00
extern "C" {
Migrate from a macro to an attribute This commit migrates from `wasm_bindgen!`-the-macro to `#[wasm_bindgen]`-the-attribute. The actual mechanics of the macro are relatively simple in just generating some shims here and there, but wrapping everything in one huge macro invocation can often seem intimidating as it gives off this feeling of "oh dear anything can happen here!" Using an attribute should curb expectations much more greatly of "oh there's just some extra stuff happening behind the scenes". The usage is otherwise relatively straightforward and close to what it was before, but check out the DESIGN.md/README.md changes for more info!
2018-02-08 03:41:33 +03:00
fn alert(s: &str);
}
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
// Export a `greet` function from Rust to JavaScript, that alerts a
// hello message.
Migrate from a macro to an attribute This commit migrates from `wasm_bindgen!`-the-macro to `#[wasm_bindgen]`-the-attribute. The actual mechanics of the macro are relatively simple in just generating some shims here and there, but wrapping everything in one huge macro invocation can often seem intimidating as it gives off this feeling of "oh dear anything can happen here!" Using an attribute should curb expectations much more greatly of "oh there's just some extra stuff happening behind the scenes". The usage is otherwise relatively straightforward and close to what it was before, but check out the DESIGN.md/README.md changes for more info!
2018-02-08 03:41:33 +03:00
#[wasm_bindgen]
fix: remove unwanted no_mangle and extern wherever applicable
2018-03-06 01:25:15 +03:00
pub fn greet(name: &str) {
Migrate from a macro to an attribute This commit migrates from `wasm_bindgen!`-the-macro to `#[wasm_bindgen]`-the-attribute. The actual mechanics of the macro are relatively simple in just generating some shims here and there, but wrapping everything in one huge macro invocation can often seem intimidating as it gives off this feeling of "oh dear anything can happen here!" Using an attribute should curb expectations much more greatly of "oh there's just some extra stuff happening behind the scenes". The usage is otherwise relatively straightforward and close to what it was before, but check out the DESIGN.md/README.md changes for more info!
2018-02-08 03:41:33 +03:00
alert(&format!("Hello, {}!", name));
Add a basic README which at least attempts
2017-12-19 03:35:36 +03:00
}
```
Readme tweaks (#606) * Use ES modules in README example * Remove introduction blog post from README While the blog post is great, the README and the guide should be a good enough intro to wasm-bindgen, and are more likely to be kept up to date.
2018-08-02 02:42:23 +03:00
Use exported Rust things from JavaScript with ECMAScript modules!
Rewrite wasm-bindgen with ES6 modules in mind This commit is a mostly-rewrite of the `wasm-bindgen` tool. After some recent discussions it's clear that the previous model wasn't quite going to cut it, and this iteration is one which primarily embraces ES6 modules and the idea that this is a polyfill for host bindings. The overall interface and functionality hasn't changed much but the underlying technology has now changed significantly. Previously `wasm-bindgen` would emit a JS file that acted as an ES6 module but had a bit of a wonky interface. It exposed an async function for instantiation of the wasm module, but that's the bundler's job, not ours! Instead this iteration views each input and output as a discrete ES6 module. The input wasm file is interpreted as "this *should* be an ES6 module with rich types" and the output is "well here's some ES6 modules that fulfill that contract". Notably the tool now replaces the original wasm ES6 module with a JS ES6 module that has the "rich interface". Additionally a second ES6 module is emitted (the actual wasm file) which imports and exports to the original ES6 module. This strategy is hoped to be much more amenable to bundlers and controlling how the wasm itself is instantiated. The emitted files files purely assume ES6 modules and should be able to work as-is once ES6 module integration for wasm is completed. Note that there aren't a ton of tools to pretend a wasm module is an ES6 module at the moment but those should be coming soon! In the meantime a local `wasm2es6js` hack was added to help make *something* work today. The README has also been updated with instructions for interacting with this model.
2018-01-30 08:20:38 +03:00
```js
Readme tweaks (#606) * Use ES modules in README example * Remove introduction blog post from README While the blog post is great, the README and the guide should be a good enough intro to wasm-bindgen, and are more likely to be kept up to date.
2018-08-02 02:42:23 +03:00
import { greet } from "./hello_world";
greet("World!");
Generate TypeScript by default instead of JS This is what's needed in the immediate future anyway, so let's do that!
2017-12-20 06:06:48 +03:00
```
Add a basic README which at least attempts
2017-12-19 03:35:36 +03:00
README: add features section describing goals/foundations/features of wasm-bindgen
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
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
## Guide
Rewrite the README using Webpack Right now Webpack probably has the most mature support for loading wasm modules, so let's show off how to do that! Additionally this commits hello world as an example to the repository.
2018-03-03 07:11:30 +03:00
Add a "nightly only" warning to documentation Official documentation is now available at https://rustwasm.github.io/docs/wasm-bindgen/, so let's leave this git repository's documentation purely for our own previewing purposes.
2019-03-07 18:42:47 +03:00
[**📚 Read the `wasm-bindgen` guide here! 📚**](https://rustwasm.github.io/docs/wasm-bindgen/)
You can find general documentation about Rust and WebAssembly
[here](https://rustwasm.github.io/docs).
Add a smorgasboard example
2018-03-03 07:19:39 +03:00
Link to API docs from README
2018-09-16 15:12:48 +03:00
## API Docs
Add a "nightly only" warning to documentation Official documentation is now available at https://rustwasm.github.io/docs/wasm-bindgen/, so let's leave this git repository's documentation purely for our own previewing purposes.
2019-03-07 18:42:47 +03:00
- [wasm-bindgen](https://docs.rs/wasm-bindgen)
- [js-sys](https://docs.rs/js-sys)
- [web-sys](https://docs.rs/web-sys)
Update README.md Co-Authored-By: alexcrichton <alex@alexcrichton.com>
2019-03-08 00:17:28 +03:00
- [wasm-bindgen-futures](https://docs.rs/wasm-bindgen-futures)
Link to API docs from README
2018-09-16 15:12:48 +03:00
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
## License
Add CI and a small README
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.
Make the README a landing page All the details are moved into the guide, where they can be properly organized and have a table of contents.
2018-06-19 21:10:41 +03:00
## Contribution
Point to the guide's contributing section instead of CONTRIBUTING.md
2018-06-19 21:49:34 +03:00
**[See the "Contributing" section of the guide for information on
hacking on `wasm-bindgen`!][contributing]**
Add CI and a small README
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.
Add section on node dependency in README
2018-02-23 16:52:45 +03:00
Fix broken link to contribution page
2018-10-05 18:25:55 +03:00
[contributing]: https://rustwasm.github.io/wasm-bindgen/contributing/index.html
Reference in New Issue Copy Permalink