Skip to content

Commit 5788e7d

Browse files
alexcrichtonalexcrichton
authored
Merge pull request #1285 from alexcrichton/tweak-docs
Tweak introductory and deployment documentation.
2 parents 74a39ce + b71f337 commit 5788e7d

18 files changed

+189
-532
lines changed

‎.travis.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ matrix:
100100
- cargo build -p wasm-bindgen-cli
101101
- ln -snf target/debug/wasm-bindgen $HOME/.cargo/wasm-bindgen
102102
- |
103-
for dir in `ls examples | grep -v README | grep -v asm.js | grep -v raytrace | grep -v no_modules`; do
103+
for dir in `ls examples | grep -v README | grep -v asm.js | grep -v raytrace | grep -v without-a-bundler`; do
104104
(cd examples/$dir &&
105105
ln -fs ../../node_modules . &&
106106
npm run build -- --output-path $HOME/$TRAVIS_BUILD_NUMBER/exbuild/$dir) || exit 1;

‎Cargo.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,6 @@ members = [
7272
"examples/hello_world",
7373
"examples/import_js",
7474
"examples/julia_set",
75-
"examples/no_modules",
7675
"examples/paint",
7776
"examples/performance",
7877
"examples/raytrace-parallel",
@@ -82,6 +81,7 @@ members = [
8281
"examples/wasm2js",
8382
"examples/webaudio",
8483
"examples/webgl",
84+
"examples/without-a-bundler",
8585
"tests/no-std",
8686
]
8787
exclude = ['crates/typescript']

‎examples/no_modules/index.html

-20
This file was deleted.

‎examples/no_modules/Cargo.toml renamed to ‎examples/without-a-bundler/Cargo.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[package]
2-
name = "no_modules"
2+
name = "without-a-bundler"
33
version = "0.1.0"
44
authors = ["The wasm-bindgen Developers"]
55
edition = "2018"

‎examples/no_modules/README.md renamed to ‎examples/without-a-bundler/README.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
# Using `--no-modules`
1+
# Without a Bundler
22

33
[View documentation for this example online][dox]
44

5-
[dox]: https://rustwasm.github.io/wasm-bindgen/examples/no-modules.html
5+
[dox]: https://rustwasm.github.io/wasm-bindgen/examples/without-a-bundler.html
66

77
You can build the example locally with:
88

‎examples/without-a-bundler/index.html

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
<html>
2+
<head>
3+
<meta content="text/html;charset=utf-8" http-equiv="Content-Type"/>
4+
</head>
5+
<body>
6+
<!--
7+
This is the JS generated by the `wasm-pack` build command
8+
9+
The script here will define a `wasm_bindgen` global where all
10+
functionality can be accessed such as instantiation and the actual
11+
functions (examples below).
12+
13+
You can customize the name of the file here with the `out-name` CLI flag
14+
to `wasm-bindgen`. You can also customize the name of the global exported
15+
here with the `no-modules-global` flag.
16+
-->
17+
<script src='./pkg/without_a_bundler.js'></script>
18+
19+
<script>
20+
// Import functionality from the wasm module, but note that it's not quite
21+
// ready to be used just yet.
22+
const { add } = wasm_bindgen;
23+
24+
async function run() {
25+
// First up we need to actually load the wasm file, so we use the
26+
// exported global to inform it where the wasm file is located on the
27+
// server, and then we wait on the returned promies to wait for the
28+
// wasm to be loaded.
29+
//
30+
// Note that instead of a string here you can also pass in an instance
31+
// of `WebAssembly.Module` which allows you to compile your own module.
32+
await wasm_bindgen('./pkg/without_a_bundler_bg.wasm');
33+
34+
// And afterwards we can use all the functionality defined in wasm.
35+
const result = add(1, 2);
36+
console.log(`1 + 2 = ${result}`);
37+
if (result !== 3)
38+
throw new Error("wasm addition doesn't work!");
39+
}
40+
41+
run();
42+
</script>
43+
</body>
44+
</html>

‎examples/no_modules/src/lib.rs renamed to ‎examples/without-a-bundler/src/lib.rs

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
use wasm_bindgen::prelude::*;
22

3-
// Called by our JS entry point to run the example
3+
// Called when the wasm module is instantiated
44
#[wasm_bindgen(start)]
55
pub fn main() -> Result<(), JsValue> {
66
// Use `web_sys`'s global `window` function to get a handle on the global
@@ -17,3 +17,8 @@ pub fn main() -> Result<(), JsValue> {
1717

1818
Ok(())
1919
}
20+
21+
#[wasm_bindgen]
22+
pub fn add(a: u32, b: u32) -> u32 {
23+
a + b
24+
}

‎guide/src/SUMMARY.md

+2-6
Original file line numberDiff line numberDiff line change
@@ -4,15 +4,11 @@
44

55
--------------------------------------------------------------------------------
66

7-
- [Whirlwind Tour](./whirlwind-tour/introduction.md)
8-
- [Basic Usage](./whirlwind-tour/basic-usage.md)
9-
- [What Just Happened?](./whirlwind-tour/what-just-happened.md)
10-
- [What Else Can We Do?](./whirlwind-tour/what-else-can-we-do.md)
117
- [Examples](./examples/index.md)
128
- [Hello, World!](./examples/hello-world.md)
139
- [Using `console.log`](./examples/console-log.md)
1410
- [Small wasm files](./examples/add.md)
15-
- [Using `--no-modules`](./examples/no-modules.md)
11+
- [Without a Bundler](./examples/without-a-bundler.md)
1612
- [Converting WebAssembly to JS](./examples/wasm2js.md)
1713
- [Importing functions from JS](./examples/import-js.md)
1814
- [Working with `char`](./examples/char.md)
@@ -30,11 +26,11 @@
3026
- [Parallel Raytracing](./examples/raytrace.md)
3127
- [web-sys: A TODO MVC App](./examples/todomvc.md)
3228
- [Reference](./reference/index.md)
29+
- [Deployment](./reference/deployment.md)
3330
- [Passing Rust Closures to JS](./reference/passing-rust-closures-to-js.md)
3431
- [Receiving JS Closures in Rust](./reference/receiving-js-closures-in-rust.md)
3532
- [`Promise`s and `Future`s](./reference/js-promises-and-rust-futures.md)
3633
- [Iterating over JS Values](./reference/iterating-over-js-values.md)
37-
- [No ES Modules](./reference/no-esm.md)
3834
- [Arbitrary Data with Serde](./reference/arbitrary-data-with-serde.md)
3935
- [Accessing Properties of Untyped JS Values](./reference/accessing-properties-of-untyped-js-values.md)
4036
- [Working with Duck-Typed Interfaces](./reference/working-with-duck-typed-interfaces.md)

‎guide/src/examples/index.md

+10-4
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,19 @@ This subsection contains examples of using the `wasm-bindgen`, `js-sys`, and
44
`web-sys` crates. Each example should have more information about what it's
55
doing.
66

7-
The source code for all examples can also be [found online][code] to download an
8-
run locally. Most examples are configured with Webpack/`wasm-pack` and can
7+
These examples all assume familiarity with `wasm-bindgen`, `wasm-pack`, and
8+
building a Rust and WebAssembly project. If you're unfamiliar with these check
9+
out the [Game of Life tutorial][gol] to help you get started.
10+
11+
The source code for all examples can also be [found online][code] to download
12+
and run locally. Most examples are configured with Webpack/`wasm-pack` and can
913
be built with `npm run serve`. Other examples which don't use Webpack are
1014
accompanied with a `build.sh` showing how to build it.
1115

1216
Note that most examples currently use Webpack to assemble the final output
13-
artifact, but this is not required! You can use the bundler of choice,
14-
`--no-modules`, or native browser ESM support as alternatives to Webpack.
17+
artifact, but this is not required! You can review the [deployment
18+
documentation][deploy] for other options of how to deploy Rust and WebAssembly.
1519

1620
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples
21+
[gol]: https://rustwasm.github.io/book/
22+
[deploy]: ../reference/deployment.html

‎guide/src/examples/no-modules.md

-20
This file was deleted.

‎guide/src/examples/without-a-bundler.md

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Without a Bundler
2+
3+
[View full source code][code]
4+
5+
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/without-a-bundler
6+
7+
This example shows how the `--no-modules` flag can be used load code in a
8+
browser directly. For this deployment strategy bundlers like Webpack are not
9+
required. For more information on deployment see the [dedicated
10+
documentation](../reference/deployment.html).
11+
12+
First let's take a look at the code and see how when we're using `--no-modules`
13+
we're not actually losing any functionality!
14+
15+
```rust
16+
{{#include ../../../examples/without-a-bundler/src/lib.rs}}
17+
```
18+
19+
Otherwise the rest of the deployment magic happens in `index.html`:
20+
21+
```html
22+
{{#include ../../../examples/without-a-bundler/index.html}}
23+
```
24+
25+
And that's it! Be sure to read up on the [deployment options] to see what it
26+
means to deploy without a bundler.
27+
28+
[hello]: hello-world.html
29+
[mod-imp]: ../reference/attributes/on-js-imports/module.html

‎guide/src/introduction.md

+21-12
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
11
# Introduction
22

3-
`wasm-bindgen` facilitates high-level interactions between wasm modules and
4-
JavaScript.
3+
This book is about `wasm-bindgen`, a Rust library and CLI tool that facilitate
4+
high-level interactions between wasm modules and JavaScript. The `wasm-bindgen`
5+
tool and crate are only one part of the [Rust and WebAssembly
6+
ecosystem][rustwasm]. If you're not familiar already with `wasm-bindgen` it's
7+
recommended to start by reading the [Game of Life tutorial][gol]. If you're
8+
curious about `wasm-pack`, you can find that [documentation here][wasm-pack].
59

6-
This project is sort of half polyfill for features like the [host bindings
7-
proposal][host] and half features for empowering high-level interactions between
8-
JS and wasm-compiled code (currently mostly from Rust). More specifically this
9-
project allows JS/wasm to communicate with strings, JS objects, classes, etc, as
10-
opposed to purely integers and floats. Using `wasm-bindgen` for example you can
11-
define a JS class in Rust or take a string from JS or return one. The
12-
functionality is growing as well!
10+
The `wasm-bindgen` tool is sort of half polyfill for features like the [host
11+
bindings proposal][host] and half features for empowering high-level
12+
interactions between JS and wasm-compiled code (currently mostly from Rust).
13+
More specifically this project allows JS/wasm to communicate with strings, JS
14+
objects, classes, etc, as opposed to purely integers and floats. Using
15+
`wasm-bindgen` for example you can define a JS class in Rust or take a string
16+
from JS or return one. The functionality is growing as well!
1317

1418
Currently this tool is Rust-focused but the underlying foundation is
1519
language-independent, and it's hoping that over time as this tool stabilizes
@@ -22,14 +26,19 @@ Notable features of this project includes:
2226
* Exporting Rust functionality to JS such as classes, functions, etc.
2327
* Working with rich types like strings, numbers, classes, closures, and objects
2428
rather than simply `u32` and floats.
29+
* Automatically generating TypeScript bindings for Rust code being consumed by
30+
JS.
2531

26-
This project is still relatively new but feedback is of course always
27-
welcome! If you're curious about the design plus even more information about
28-
what this crate can do, check out the [design doc].
32+
With the addition of [`wasm-pack`] you can run the gamut from running Rust on
33+
the web locally, publishing it as part of a larger application, or even
34+
publishing Rust-compiled-to-WebAssembly on NPM!
2935

3036
[host]: https://github.com/WebAssembly/host-bindings
3137
[design doc]: https://rustwasm.github.io/wasm-bindgen/contributing/design/index.html
3238
[dom-ex]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/dom
3339
[console-log]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/console_log
3440
[perf-ex]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/performance
3541
[hello-online]: https://webassembly.studio/?f=gzubao6tg3
42+
[rustwasm]: https://rustwasm.github.io/
43+
[gol]: https://rustwasm.github.io/book/
44+
[wasm-pack]: https://rustwasm.github.io/wasm-pack/book/

‎guide/src/reference/deployment.md

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Deploying Rust and WebAssembly
2+
3+
At this point in time deploying Rust and WebAssembly to the web or other
4+
locations unfortunately isn't a trivial task to do. This page hopes to serve
5+
as documentation for the various known options, and as always PRs are welcome
6+
to update this if it's out of date!
7+
8+
## Bundlers
9+
10+
The default output of `wasm-bindgen` assumes a model where the wasm module
11+
itself is natively an ES module. This model, however, not natively implemented
12+
in any JS implementation at this time. As a result, to consume the default
13+
output of `wasm-bindgen` you will need a bundler of some form.
14+
15+
> **Note**: the choice of this default output was done to reflect the trends of
16+
> the JS ecosystem. While tools other than bundlers don't support wasm files as
17+
> native ES modules today they're all very much likely to in the future!
18+
19+
Currently the only known bundler known to be fully compatible with
20+
`wasm-bindgen` is [webpack]. Most [examples] use webpack, and you can check out
21+
the [hello world example online] to see the details of webpack configuration
22+
necessary.
23+
24+
[webpack]: https://webpack.js.org/
25+
[examples]: ../examples/index.html
26+
[hello world example online]: ../examples/hello-world.html
27+
28+
## Without a Bundler
29+
30+
If you're not using a bundler but you're still running code in a web browser,
31+
`wasm-bindgen` still supports this! For this use case you'll want to use the
32+
`--no-modules` flag. You can check out a [full example][nomex] in the
33+
documentation, but the highlights of this output are:
34+
35+
* When using `wasm-pack` you'll pass `--target no-modules`, and when using
36+
`wasm-bindgen` directly you'll pass `--no-modules`.
37+
* The output can natively be included on a web page, and doesn't require any
38+
further postprocessing.
39+
* The `--no-modules` mode is not able to use NPM dependencies nor local JS
40+
snippets (both currently [proposed][rfc1] [features][rfc2])
41+
* You'll want to review the [browser requirements] for `wasm-bindgen` because
42+
no polyfills will be available.
43+
44+
[nomex]: ../examples/without-a-bundler.html
45+
[rfc1]: https://github.com/rustwasm/rfcs/pull/6
46+
[rfc2]: https://github.com/rustwasm/rfcs/pull/8
47+
[browser requirements]: browser-support.html
48+
49+
Despite these limitations almost all code today is compatible with
50+
`--no-modules`, but this area is actively being worked on to improve the
51+
experience so the experience here may be tweaked over time!
52+
53+
## Node.js
54+
55+
If you're deploying WebAssembly into Node.js (perhaps as an alternative to a
56+
native module), then you'll want to pass the `--target nodejs` flag to
57+
`wasm-pack` or the `--nodejs` flag to `wasm-bindgen`.
58+
59+
Like the "without a bundler" strategy, this method of deployment does not
60+
require any further postprocessing. The generated JS shims can be `require`'d
61+
just like any other Node module (even the `*_bg` wasm file can be `require`'d
62+
as it has a JS shim generated as well).
63+
64+
Note that this method requires a version of Node.js with WebAssembly support,
65+
which is currently Node 8 and above.
66+
67+
## NPM
68+
69+
If you'd like to deploy compiled WebAssembly to NPM, then the tool for the job
70+
is [`wasm-pack`]. More information on this coming soon!
71+
72+
[`wasm-pack`]: https://rustwasm.github.io/wasm-pack/book/

0 commit comments

Comments
 (0)