rustwasm/book

The Rust and WebAssembly Book

The Rust and WebAssembly Book

This small book describes how to use Rust and WebAssembly together. It also consists of tutorials with cool exercises.

Read the Book | Contributing | Chat

_{Built with 🦀🕸 by The Rust and WebAssembly Working Group}

About

This repo contains documentation on using Rust for wasm, common workflows, how to get started and more as you dive deeper. It acts as a guide for doing some really neat things with rust.

If you would like to start learning how to use Rust and WebAssembly together, you can read the book online here.

Open issues for improving the Rust and WebAssembly book.

Building the Book

The book is made using mdbook. To install it you'll need cargo installed. If you don't have any Rust tooling installed, you'll need to install rustup first. Follow the instructions on the site in order to get setup.

Once you have that done then just do the following:

$ cargo install mdbook

Make sure the cargo install directory is in your $PATH so that you can run the binary.

Now just run this command from this directory:

$ mdbook build

This will build the book and output files into a directory called book. From there you can navigate to the index.html file to view it in your browser. You could also run the following command to automatically generate changes if you want to look at changes you might be making to it:

$ mdbook serve

This will automatically generate the files as you make changes and serves them locally so you can view them easily without having to call build every time.

The files are all written in Markdown so if you don't want to generate the book to read them then you can read them from the src directory.

book's Issues

Overhaul "Deploying to Production" chapter of GoL tutorial

We talked about this at today's WG meeting.

It is good to ahve this chapter, but we shouldn't apepar to be blessing one particular way to deploy/serve web apps, and this can create the false impression that rust+wasm requires special handling in deployment that is different from other web apps. Additionally, what we currently have is documentation that we have to maintain and keep up to date that isn't even about our core toolchain.

Instead, we should

• make sure to highlight that deploying to production is the same as any other web app
• link to many different kinds of servers and production/deployment external docs (eg webpack production builds, digital ocean docs, apache docs, nginx docs, etc)

Add a wasm-bindgen hello world to the book #127

Link to old issue

Issue was opened by @johnthagen

I found Alex's blog post on wasm-bindgen to be extremely enlightening: https://hacks.mozilla.org/2018/04/javascript-to-rust-and-back-again-a-wasm-bindgen-tale/

Could something along these lines be brought into the book, perhaps even in hello world style? It seems like the next step after learning how to expose C ABI functions like those in the current hello world example.

If this was brought into the book, it could be maintained as the ecosystem evolves.

The stuff he describes in his blog seems simpler than jumping straight to Conway's Game of Life.

npm link after npm install doesn't work

Where in the docs did you come across this?
Section npm link and npm run:
https://rustwasm.github.io/book/game-of-life/hello-world.html

Describe what about it does not make sense
The sequence of the steps isn't correct, see below.

Why does it not make sense?
If it's run as described then the wasm-game-of-life won't be linked probably by npm and as result the program can't be launched

How could we improve it?
I sent already a PR, after figuring it out with the invaluable help of @fitzgen 🙏

Document workflows

Link to old issue

Issue was opened by @aturon

Ideally this repo would contain some additional markdown documents giving our current "best practice workflows", e.g. including running wasm-gc and other tools.

Create example projects

Books are great but sometimes people learn best by having examples, especially more complex ones, to learn from! We should create a few projects that showcase wasm, can be used as an example, and can be linked from in the book for easy reference.

Publishing section of Game of Life Tutorial

We will actually want to write this one out instead of leaving it as Coming Soon. This is a tracking issue for it until that changes.

There's some discussion of how we want to do this in #16 and might still need more discussion

Integrating wasm-pack into Game of Life

In today's meeting we wanted to discuss how we would integrate wasm-pack into the Game of Life tutorial so we can teach people how to publish stuff as well. However, this makes things a bit difficult because how the tutorial is written to work and how wasm-pack works are a bit incompatible. This would require a bit of an undertaking to implement but what we need to discuss here is this:

• Do we want to do this or would it be better as an appendix resource as it currently is?
• If we do integrate it what would the scope be?
• How would we want to change the tutorial to work with it?
• How would we change the template to work with it?
• Are there other issues with this that we haven't discussed?

Expanding the Rust wasm Book

link to old issue

Issue opened by @mgattozzi

In #12 we added the book to act as a central part of documenting and working with wasm and Rust.
We should continue to expand it as we hash things out and continue to work on wasm. I've compiled a list of tasks below to help grow and maintain the book. This can be a starting point for those wishing to help out but aren't really sure what to do.

Tasks

• Document workflows: This is part of #7. We need to document different ways to work with and utilize Rust. For instance how to use various bits of tooling to shrink binaries or clean them up beyond what the wasm32 target does, or passing data into and out of JS for instance. The book tells people how to setup the environment and run hello world. Now we need to go beyond that.

• Document tools available to users: We have this in #10 but for someone just picking up the book and who doesn't want to wade through the issue tracker having a list would be good.
  Update: In #42 we added the page but this can be expanded as it is a living document! Finding more tools to add and removing old or unused ones overtime will be important.

• Expanding #28 into it's own section: This will allow users who want to make a crate know how to make it easier to work with wasm.

• Current state of wasm32 development with rustc: Not everyone has the time to read all the PRs, tracking issues, and things going on with it and having a sort of changelog of sorts would help us keep track of changes specific to wasm but also give consumers of the wasm32 backend a way to see what's changing.

• Collection of articles: People have talked about their experiences online with Rust and wasm. We should bring them into a place that's easy to access and learn from. This also allows us to supplement the book as it's expanded

• Collection of demos: Lots of people are making things with wasm and Rust. Let's collect them all into a central place so people can see it in action!

• Tutorials and guides: What is wasm? What is wat? How can someone learn it and utilize it with Rust? The WebAssembly website has some great resources but they focus more on C++ being used and not everyone wants to look at standards. A lot of the docs are what web assembly is and less how to use it. Let's make some high quality Rust examples and guides!

  • Tutorial for Writing a Library for JS: Scenarios where we are writing a Rust crate that will be compiled into a WebAssembly module that is used as a library by JavaScript. For example, perhaps the hot portion of some JS is being re-written in Rust/wasm. Similar to scenarios like Oxidizing Source Maps with Rust and WebAssembly
  • Tutorial for Writing Pure-Rust Web Apps: Scenarios where there isn't any hand-written JS being loaded, only machine generated glue to access DOM APIs, and all the magic is in pure Rust.

There's likely more we can do to increase our documentation efforts but this seems like a good few steps we can take to really get our documentation efforts underway.

Unsure how to test performance on MacOS

Where in the docs did you come across this?
In the section on Time-Profiling, the author mentions using the Linux tool perf to test the results of cargo bench.

Describe what about it does not make sense
Since I'm using a Mac, I don't have access to the perf tool, and I don't know of any equivalent tools I could use to get similar data.

How could we improve it?
It would be nice to mention additional tools that could be used in MacOS or Windows. It would be even more helpful if you could also link to additional tutorials for how use them to test Rust

hello world, rebuilding unclear

Where in the docs did you come across this?

https://rustwasm.github.io/book/game-of-life/hello-world.html

Describe what about it does not make sense

Exercises says "rebuild the .wasm binary,", but no text before that explains how you actually do that. The only command that was mentioned before is wasm-pack init,

Why does it not make sense?

according to rustwasm/wasm-pack#185 the correct command is

wasm-pack init --mode no-install 

but that is non obvious

How could we improve it?

mention wasm-pack init --mode no-install

Hello World instructions unclear. #126

link to old issue

Issue was opened by @cldershem

There are a few pieces in the Hello World chapter that are not as clear as they could be.

1. code snippets include optional dependency

2. Instructions on serving the wasm file are confusing.

1 - The file name referred to in the html/script is hello_world.gc.opt.wasm which is only the name of the file if you've chosen to 'make the binary even smaller'. Because this is an optional step, one may not take it, especially if they're just trying to experiment quickly or getting a working setup. A simple fix would be to not name the file differently during the optional step.

2 - There are two ways to serve the wasm file, one using the https crate (or a webserver one may have already installed on the machine) and another using the Python3 simple server. However the instructions in the Note say there is a stipulation on the webservers that may be used. The majority of users checking this out for the first time will likely be on a machine without a real webserver installed. The Python3 server is used fairly ubiquitously in example code throughout the web, so I think it might be a good idea to list this first.

It is confusing to include both example in a Hello World section. I think it might benefit users to only include one, either require the https crate to be used (which is a reasonable dependency) or only list the Python3 example with a note of the caveat and that there is a potentially better way to do it when the user gets to the real world.

Missing `cargo update` step in docs

Where in the docs did you come across this?

https://rustwasm.github.io/book/game-of-life/hello-world.html

Describe what about it does not make sense. Why does it not make sense?

When running npm run build-debug, cargo asks me to do cargo update first, because Cargo.lock says the project is linked against wasm-bindgen 0.2.13 and I was using 0.2.17.

How could we improve it?

Adding the cargo update step to the docs (or maybe removing Cargo.lock entirely) would help

[game-of-life] Host each chapter's finished version somewhere (or use wasm studio?) #116

link to old issue

Issue opened by @fitzgen

And link to them from the tutorial. Multiple requests to do this now.

Dependencies not up to date

Where in the docs did you come across this?
I am new to Rust and I am coding along tutorial on Game of Life.
Describe what about it does not make sense
Cargo.lock is not up to date as dependencies have bumped up their versions.
Why does it not make sense?
Rust fails to compile
How could we improve it?
update proc-macro2 to latest v0.4.9 cargo update -p proc-macro2
update wasm-bindgen to latest v0.2.13 cargo update -p wasm-bindgen

Add a reference section about unwinding and panics

This section should:

• Explain the current state of unwinding, ie how panic=abort is the only option.
• Describe what "aborting" means in this context, and how it turns into a JS error, and how Drop implementations are not run.
• Warn against the dangers of re-entering wasm after it has "aborted" due to inconsistent state from Drop impls not running.
• Describe how JS can handle "aborts" by creating a new instance of the wasm module.
• Briefly talk about potential future support for unwinding and link to the proposal.

plan of translate chinese 🇨🇳

Add h2|h* to source readme.md

## Translations

- [![china](https://raw.githubusercontent.com/gosquared/flags/master/flags/flags/shiny/24/China.png) **中文/Chinese**](https://github.com/chinanf-boy/rustwasm-book)

---

Translations

• 中文/Chinese

I can finish tomorrow 😊

Getting Started reference to `wasm-opt` could be more clear. #125

link to old issue

Issue was opeed by @cldershem

In Getting Started the sentence mentioning wasm-opt is a little confusing. It states that in some circumstances one might want to install wasm-opt from the binaryen toolkit, but doesn't say how one does that. Even after clicking through to the toolkit's own README it isn't clear how to install the package.

I'm sure if I took sometime I could potentially figure this out by installing binaryen, but that looks to be a commitment since that involves compiling from source. Since this book is possibly the first substantial intro to Rust & Wasm someone might have, it would be good to keep the barrier of entry as low as possible. A little more of an explanation that this is advanced usage or leaving that as a footnote to move to a later section of the book might help make it less of an issue.

Cannot build first example

I'm just trying to follow the steps in the tutorial. Any tips would be greatly appreciated! I may be missing something obvious, because I've never worked with Rust or wasm before.

https://rustwasm.github.io/book/game-of-life/hello-world.html

My steps:

cargo generate --git https://github.com/rustwasm/wasm-pack-template

# I called my project try-wasm

cd try-wasm

wasm-pack init

I get:

  [1/8] 🔧  Checking crate configuration...
  [2/8] 🎯  Adding WASM target...
- [3/8] 🌀  Compiling to WASM...
Compilation of your program failed. stderr:

Here is the full output:

Compilation of your program failed. stderr:

$ wasm-pack init

  [1/8] 🔧  Checking crate configuration...
  [2/8] 🎯  Adding WASM target...
- [3/8] 🌀  Compiling to WASM...
Compilation of your program failed. stderr:

    Updating registry `https://github.com/rust-lang/crates.io-index`
 Downloading wasm-bindgen v0.2.19
 Downloading wasm-bindgen-macro v0.2.19
 Downloading wasm-bindgen-macro-support v0.2.19
 Downloading wasm-bindgen-shared v0.2.19
 Downloading wasm-bindgen-backend v0.2.19
   Compiling proc-macro2 v0.4.15
   Compiling unicode-xid v0.1.0
   Compiling version_check v0.1.4
   Compiling ryu v0.2.6
   Compiling serde v1.0.75
   Compiling wasm-bindgen-shared v0.2.19
   Compiling itoa v0.4.2
   Compiling cfg-if v0.1.5
   Compiling log v0.4.4
   Compiling lazy_static v1.1.0
   Compiling quote v0.6.8
   Compiling syn v0.14.9
   Compiling serde_json v1.0.26
   Compiling serde_derive v1.0.75
   Compiling wasm-bindgen-backend v0.2.19
   Compiling wasm-bindgen-macro-support v0.2.19
   Compiling wasm-bindgen-macro v0.2.19
   Compiling wasm-bindgen v0.2.19
   Compiling try-wasm v0.1.0 (file:///Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm)
warning: function is never used: `set_panic_hook`
  --> src/utils.rs:11:9
   |
11 |         pub fn set_panic_hook() {}
   |         ^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: #[warn(dead_code)] on by default

error: linking with `rust-lld` failed: signal: 6
  |
  = note: "rust-lld" "-flavor" "wasm" "-L" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps/umap_wasm.umap_wasm.bkno5jfr-cgu.0.rcgu.o" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps/umap_wasm.umap_wasm.bkno5jfr-cgu.1.rcgu.o" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps/umap_wasm.umap_wasm.bkno5jfr-cgu.2.rcgu.o" "-o" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps/umap_wasm.wasm" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps/umap_wasm.44e0i2zwvzwfmnu7.rcgu.o" "--gc-sections" "-O3" "-L" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps" "-L" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/release/deps" "-L" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps/libwasm_bindgen-f9f62e4f9e995bb5.rlib" "/Users/slowikow/Dropbox/work/github.com/slowkow/try-wasm/target/wasm32-unknown-unknown/release/deps/libcfg_if-954cfacc8a40931a.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/libstd-b0efc82f64d03095.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/libpanic_abort-4f93017645c0d252.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/libunwind-c43a3d8cf78f9d5a.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/liblibc-68373f2b6bc18151.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/liballoc_system-40a64b71ec5a8f18.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/libdlmalloc-f6caffaf44cc60a0.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/liballoc-863f2b2485046aef.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/libcore-21433d3b7663b55b.rlib" "/Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/wasm32-unknown-unknown/lib/libcompiler_builtins-bf63ca2c3bc4de53.rlib" "--no-threads" "-z" "stack-size=1048576" "--stack-first" "--allow-undefined" "--no-entry" "--export-table"
  = note: dyld: Library not loaded: @rpath/libLLVM.dylib
            Referenced from: /Users/slowikow/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/x86_64-apple-darwin/bin/rust-lld
            Reason: image not found


error: aborting due to previous error

error: Could not compile `try-wasm`.

To learn more, run the command again with --verbose.

Versions:

cargo 1.28.0 (96a2c7d16 2018-07-13)

wasm-pack 0.4.2

rustc 1.28.0 (9634041f0 2018-07-30)

rustup 1.13.0 (ea9259c1b 2018-07-16)

$ rust-lldb --version
lldb-902.0.79.7
  Swift-4.1

Add redirects from rust-lang-nursery.github.io

I had bookmarked https://rust-lang-nursery.github.io/rust-wasm/game-of-life/introduction.html to check out later, but was surprised today to find that the link was dead. It would be nice to leave some kind of redirect in place to the new home of the rust wasm book (which is https://rustwasm.github.io/book/game-of-life/introduction.html for those that are too lazy to go find it)

(also woo first issue!)

Despite "title" entry in book.toml, it isn't in <title>

I see "Introduction - " as the <title> of the book, when I would expect "Introduction - Rust and WebAssembly".

Setup exercise has confusing hint

Where in the docs did you come across this?

The second exercise at https://rustwasm.github.io/book/game-of-life/setup.html#exercises suggests introducing an error (passing one argument to a Rust function expecting two) and looking at the developer tools to see the results.

Describe what about it does not make sense

The hint to look at the developer tools makes me think I should see an error in the console, but I see... nothing!

Why does it not make sense?

The wording of the exercise sets me up to believe that it will demonstrate some sort of error reporting, but the result is the opposite of that.

How could we improve it?

Explicitly state the expected results, so I can't be surprised by what I find.

P.S. Was there supposed to be an error message? I'm paranoid that I screwed something up and did not get the expected results. The book doesn't tell me!

Write a CONTRIBUTING.md

We need to write up how people can contribute. Also need to update the corresponding goals doc on rustwasm/team

Add epub format

Please generate an epub ebook file.

I'm opening a PR to do this with mdbook-epub.

Switch the Game of Life tutorial over to using rustwasm/rust_wasm_template

Link to old issue

Issue Opened by @fitzgen

This would involve:

1. Checking out the rustwasm/wasm_game_of_life repo's chapter-zero branch, and merging rustwasm/rust_wasm_template's master branch. This will involve resolving a bunch of conflicts.

2. Merging chapter-zero into chapter-one, etc. and making pull requests to rustwasm/rust_wasm_template for each of them.

3. Rewriting the relevant snippets of the game of life tutorial text to refer to cloning the rustwasm/rust_wasm_template.

Happy to help someone who wants to try their hand at this :)

No `www` dir created by the `npm init wasm-app www` command in the tutorial.

Describe the bug
No www dir created by the npm init wasm-app www command in the tutorial.

To Reproduce
Steps to reproduce the behavior:

1. cargo generate --git https://github.com/rustwasm/wasm-pack-template
2. Enter wasm-game-of-life for the project name
3. cd wasm-game-of-life
4. wasm-pack init
5. npm init wasm-app www
6. Observe that there is no www directory created, contrary to what is said in https://rustwasm.github.io/book/game-of-life/hello-world.html#putting-it-into-a-web-page

Expected behavior
I expected a www directory so that I could continue the tutorial.

Add section(s) about wasm support in general crates on crates.io

• Should describe what popular crate authors should do to support wasm (eg, have wasm-bindgen et al as an optional dependency that is enabled when targeting wasm32-u-u)

• Describe which kinds of crates will work out of the box as dependencies when targeting wasm32-u-u (no C deps, no file I/O or system calls, etc)

Book copies code not displayed due to mdbook bug

https://rustwasm.github.io/book/hello-world.html

Some code on this page is incorrect, and is different from the source code. Presumably it was changed at some point and the site wasn't updated? Here is the offending snippet:

# #![allow(unused_variables)]
#fn main() {
#[no_mangle]
pub extern fn add_one(a: u32) -> u32 {
    a + 1
}
#}

How to do a production build

Where in the docs did you come across this?
Chapter 8.1.1 Setup

Describe what about it does not make sense
The documentation talks about how to use webpack-dev-server to serve the files while it does not mention how to use production builds i.e. not use dev-server.

Why does it not make sense?
webpack-devserver should not be used in production.

Additionally it feels weird not to talk about how to serve the bundled code from another server.

How could we improve it?

Write a section that explains how to bundle code for production use(not just the wasm-code but the whole web-pack bundle) and how to serve the bundled files(i.e. which files to serve with other essential information like which mime-type the files should have).

Split Book into Four Sections #85

link to old issue

Issue opened by @mgattozzi

Today in the WG meeting we discussed who wasm and this book is for and we struck upon three groups:

1. Those who want to use wasm in a JS library
2. Those who want to use Rust only for a web app via wasm
3. Those who want to use wasm as a cross platform binary and not just the web

Each group has different restrictions and wants. For instance those who would want to run a wasm executable file on a computer could care less about how to do JS interop. Those wishing to interact with JS would want to know however.

This creates a bit of a conflict when developing the documentation. They'll have to skip sections they might not want to read. Even worse if this is their first introduction to wasm and what they want to use it for they will likely be left confused.

This leads us to the current goal: splitting up the book. It'll be four sections:

1. Things that span all three groups, such as setting up the tool chain, what wasm is etc.
2. Library for JS - Tools, tutorials, information etc. specific to this domain
3. Pure Rust Web App - Tools, tutorials, information etc. specific to this domain
4. Universal Binary - Tools, tutorials, information etc. specific to this domain

for this include:

• Restructure the book to have the 4 top level sections and an introduction explaining that
• Breaking out what's currently there into the four sections
• Provide some external resources for those sections not currently expanded much

book: Add section about `wasm2asm` fallback to support IE11 and older browsers that don't have WebAssembly

link to old issue

Issue Opened by @fitzgen

The wasm2asm tool in binaryen (soon to be renamed wasm2js) is a near feature complete solution for compiling wasm into JS so that you can support IE11 and older browsers that don't have support for WebAssembly.

We should add a section to the book about how to make this work, since it is a pretty common need.

Split out reference material from Game of Life tutorial

We have a bunch of long-form text in the tutorial that would benefit from being split out into reference pages that can be read without the rest of the Game of Life tutorial as context (either because you just want to double check / remember how to do something, or because you aren't going through the tutorial at all).

How to help:

• Copy the section out of src/game-of-life/whatever.md to src/reference/whatever.md.
• Edit src/reference/whatever.md so that
  • It doesn't reference the Game of Life tutorial, and the content can be read on its own without doing the tutorial.
  • It is "bullet point-y", concise, and is not long-winded. Something you quickly can scan as a reference.
• Edit src/game-of-life/whatever.md so that it generally doesn't duplicate information described in the new reference page. For example, instead of explaining how to use console.log with a browser's developer console before digging into adding logging to a Game of Life function, it should point to the reference page for logging to the developer console, and then show the logging in the Game of Life function.
• Submit a pull request :)

Sections to do:

• Debugging
  • The debugging section should also link to rust/wasm related issues in devtools issue trackers, and the w3c wasm CG subcharter for debugging
• Time Profiling
• Shrinking .wasm Code Size

Downplay cost of calling between JS <--> wasm

In https://rustwasm.github.io/book/game-of-life/implementing.html#interfacing-rust-and-javascript we describe calling between wasm and JS as something that is potentially expensive and that one should try and minimize. My understanding is that this may be unnecessary now, and that all engines have low-overhead paths for these calls.

@bnjbvr, maybe you can say a little more about this and confirm/deny it? Do you have any suggested edits to point (3) in the section linked above? Thanks!

wasm_game_of_life_bg is unexplained

Reading the docs, there's the following code to add when trying out the examples:

import { memory } from "./wasm_game_of_life_bg";

Yet, nowhere does it explain what memory() does or where wasm_game_of_life_bg came from?

Add a section about common memory management patterns between wasm and JS

This would be a new reference sub-section.

Things to mention:

• Dynamically allocated objects owned by JS must be manually freed by JS

• To help alleviate that pain, mention the JS equivalent of RAII:

  function withResource(f) {
      let resource = new Resource();
      try {
          return f(resource);
      } finally {
          resource.free();
      }
  }

  also the async version of that, with return await f(resource);

• Static globals in rust that don't need to have their lifetime managed by JS

• Mention upcoming GC weakrefs, link to tracking page, explain their relevance to cleaning up objects in wasm

• Mayyyybe mention how one could build reference counting in JS of dynamically allocated wasm objects? I don't know of anyone actually doing this, so maybe not mention it until then?

Anything else?

Make wasm Game of Life default tutorial

There's a lot of just mishmashed stuff in the book and we want to make the GoL the go to introduction to setting up the tool chain, getting started with a simple hello world of "can it run" and then actually learning new things. This means the book needs to get restructured as such:

• The game of life is the tutorial starting after the intro and setup of the toolchain
• Rename tutorials Appendices and place Tools, Workflows, and Javascript Interoperation in there
• Probably cut Hello World, but that can be discussed in the PR if others feel strongly about it

A bit involved but it would help bring us in line with our 2018 goals

Use `wasm-pack publish --scope <username> --access public` in publishing chapter

Waiting on a new wasm-pack release.

Right now we tell people to add their username to the end of the package name, but instead we should use scopes and --access public

Update wasm-pack tutorial paths #154

Link to old issue

This issue was opened by @mgattozzi

We're just waiting for a 0.2 release of wasm-pack right now for this issue. In https://github.com/rust-lang-nursery/rust-wasm/pull/151 we changed a path reference from ./node_modules/@MYSCOPE/wasm-add/wasm_add.js to @MYSCOPE/wasm-add/wasm_add.js. As was noted in #151 after ashleygwilliams/wasm-pack#94 is closed we can shorten this further to @MYSCOPE/wasm-add which is more idiomatic for JS.

Mentoring instructions:

1. In src/wasm-pack/run-the-code.md change the import statement of index.js to the above statement.
2. Test that the changes work as part of the tutorial with the new syntax

Add tests to the Game of Life tutorial

Using wasm-bindgen-test: https://github.com/rustwasm/wasm-bindgen/tree/master/crates/test

How do you fire the fps timer?

In "8.1.6. Time Profiling", there is an fps timer created. But as my Javascript is lacking, I'm not able to follow along with the current documentation on where to add the code to trigger the render().

Update docs to use non submodule wasm_game_of_life repo

This is a linked issue with rustwasm/wasm_game_of_life#30 and the update for this rustwasm/wasm_game_of_life#31 will need to be merged simultaneously. Currently working on it.

Add PR template

Now that we're adding a CONTRIBUTING.md it would be cool to have a template for new pull requests to help out new and old contributors!

youtube embed iframe broken in `/src/game-of-life/rules.md`

Describe the bug
iframe html is just hanging out in the markdown

To Reproduce
Steps to reproduce the behavior:

1. Go to '/src/game-of-life/rules.md'
2. Look at bottom of page
3. YouTube embed is broken

Expected behavior
Working video or link out to YouTube

File Issues for unclear bits of documentation

For those of us who do wasm and things regularly we're going to miss out on what is unclear or not explained well. Help us by filing issues on things that are unclear in the book! It's an easy task to get involved with, opens up more things for us to fix, and helps us find out what still needs improvement!

Dead image links in Game of Life explanation

Describe the bug
A clear and concise description of what the bug is.

To Reproduce
Steps to reproduce the behavior:

1. Go to /src/game-of-life/rules.md
2. Look for image with address https://github.com/rustwasm/book/blob/master/src/game-of-life/images/game-of-life/initial-universe.png
3. Look for image with address https://github.com/rustwasm/book/blob/master/src/game-of-life/images/game-of-life/next-universe.png
4. Go to /src/game-of-life/implementing.md
5. Look for image with address https://github.com/rustwasm/book/blob/master/src/game-of-life/images/game-of-life/universe.png
6. All images are missing due to 404

Expected behavior
Either no image tag or a valid image inside the image tag

Screenshots

wasm-pack tutorial out of date #174

Link to old issue

Issue Opened by @mgattozzi

This was brought up in the example repo and the code has been updated there but we need to also update the code in the tutorial here.

mgattozzi/wasm-add#1 (comment)

@adityac8 said they would do this and update the book here.

dead link in time-profiling.html

https://rustwasm.github.io/book/game-of-life/time-profiling.html#developer-tools-profilers
Under Developer Tools Profilers , the link build with debug symbols is wrong (gives 404 error) .
I tried fixing it but I got so many different results, for example it actually works with mdbook serve .
However if I build with mdbook build then visit the page manually, it doesn't work but in this case its fixed by appending .. to the link path.

It's not actually clear from the readme how to start using the book

Where in the docs did you come across this?

I was looking at /README.md and realized that I didn't actually know how to start using the book until I read through the whole documentation very carefully and realized that the quickest way to start reading it was to navigate to /src and start reading the markdown files.

Describe what about it does not make sense

The information about the easiest way to read the useful documentation and tutorials in the book should be the first thing in the README.md, which should be a document describing the project in this repo.

Why does it not make sense?

The vital information is at the end of the document in an aside.

How could we improve it?

Add a Getting Started section at the beginning that describes the things you can do with the book (read it, run examples from it, etc) and tells you how to do them.

Hello World - Someone who's never touched web is lost.

Thanks for writing this book!

Related issue here

I'm 100% new to web stuff, and understand this book isn't there for that. I raise this issue, as I hope it can handle fellas such as myself productively without changing what this book is for. With that said: The Issue...

"And we can test it out with ." at that point I don't know what to do. I would like to be able at least know where to go so I might learn the assumed knowledge needed. Things like where to put the file, how to run the file, etc. I know I can go and find this myself, and I will be doing this, but having a link in a foot-note, for example, would give me confidence I'm taking the right approach.

A foot-note example: "If this part is not making sense, [here] is a book that can get you started." For me, that would make the lessons in this book much more accessible.

Add `wasm-bindgen-futures` to crates you should know section

Its source is in the wasm-bindgen repo: https://github.com/rustwasm/wasm-bindgen/tree/master/crates/futures

This would go in the "Interacting with JavaScript and the DOM" section.'

Here it is on crates.io: https://crates.io/crates/wasm-bindgen-futures

Its API documentation has more details about what it is, and should be more than enough to inform what should go in the ~one paragraph summary that would be added to the crates you should know section: https://rustwasm.github.io/wasm-bindgen/api/wasm_bindgen_futures/

use wasm-pack-template in the wasm-pack tutorial