diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 5018c56e..08f4145e 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -297,7 +297,7 @@ --- - [WebAssembly basics](webassembly.md) -- [Load a WASM module](webassembly/load-wasm-module.md) +- [Load a Wasm module](webassembly/load-wasm-module.md) - [Expose a method](webassembly/expose-method.md) - [Error handling for exposed methods](webassembly/expose-method/error-handling.md) - [Import Method](webassembly/import-method.md) diff --git a/src/rust-wasm-template/README.md b/src/rust-wasm-template/README.md index d7448476..d457f258 100644 --- a/src/rust-wasm-template/README.md +++ b/src/rust-wasm-template/README.md @@ -1,6 +1,6 @@ # rust-wasm-template -This repository contains the minimum amount of code needed to experiment with WebAssembly. Including a web server to serve the HTML and WASM as well as the javascript boilerplate needed to load WASM. +This repository contains the minimum amount of code needed to experiment with WebAssembly. Including a web server to serve the HTML and Wasm as well as the javascript boilerplate needed to load Wasm. - `static` contains the static files including compiled webassembly. - `src/lib.rs` contains the Rust code. @@ -51,7 +51,7 @@ cargo server Visit http://localhost:8000 -## Build WASM and copy target to the correct path +## Build Wasm and copy target to the correct path ``` wasm-pack build --target web --out-dir static/wasm diff --git a/src/rust-wasm-template/static/index.html b/src/rust-wasm-template/static/index.html index a66a99bc..fa61ecb1 100644 --- a/src/rust-wasm-template/static/index.html +++ b/src/rust-wasm-template/static/index.html @@ -11,13 +11,13 @@ Comprehensive Rust 🦀 WebAssembly Template

- This repository contains the minimum amount of code needed to experiment with WebAssembly. Including a web server to serve the HTML and WASM as well as the javascript boilerplate needed to load WASM. + This repository contains the minimum amount of code needed to experiment with WebAssembly. Including a web server to serve the HTML and Wasm as well as the javascript boilerplate needed to load Wasm.

Edit server/files/index.mjs to edit the Javascript.

-WASM output: +Wasm output:

diff --git a/src/webassembly.md b/src/webassembly.md index 866df7c8..fa81c4b4 100644 --- a/src/webassembly.md +++ b/src/webassembly.md @@ -1,11 +1,11 @@ # WebAssembly basics -WebAssembly (WASM) is a binary instruction format designed to bring more languages to web browsers (historically, Javascript was the only available choice.) WASM is designed as a portable target for compilation of high-level languages like Rust, enabling it to be used in web applications. WASM has also grown beyond its scope because it can be run in a number of use cases beyond the web, including [nodejs](https://nodejs.dev/en/learn/nodejs-with-webassembly/) or the [Ethereum WebAsssembly Runtime](https://ewasm.readthedocs.io/en/mkdocs/README/) +WebAssembly (Wasm) is a binary instruction format designed to bring more languages to web browsers (historically, Javascript was the only available choice.) Wasm is designed as a portable target for compilation of high-level languages like Rust, enabling it to be used in web applications. Wasm has also grown beyond its scope because it can be run in a number of use cases beyond the web, including [nodejs](https://nodejs.dev/en/learn/nodejs-with-webassembly/) or the [Ethereum WebAsssembly Runtime](https://ewasm.readthedocs.io/en/mkdocs/README/) -Rust is often considered as one of the best languages to compile to WebAssembly due to its safety, performance, and rather expansive WASM ecosystem. +Rust is often considered as one of the best languages to compile to WebAssembly due to its safety, performance, and rather expansive Wasm ecosystem. # Setting up the environment -There are multiple frameworks to create WASM libraries from Rust. We will focus on [wasm-pack](https://rustwasm.github.io/docs/wasm-pack/introduction.html) and [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/). +There are multiple frameworks to create Wasm libraries from Rust. We will focus on [wasm-pack](https://rustwasm.github.io/docs/wasm-pack/introduction.html) and [wasm-bindgen](https://rustwasm.github.io/wasm-bindgen/). WebAssembly needs to be run in a browser or a VM, therefore we will use a different set up for this class. Please navigate to [rust-wasm-template](https://github.com/google/comprehensive-rust/tree/main/src/rust-wasm-template) to view the installation instructions. Feel free to either clone the repository to run it locally, or open a new [Codespace on Github](https://codespaces.new/google/comprehensive-rust) diff --git a/src/webassembly/expose-method.md b/src/webassembly/expose-method.md index a1e765de..aaa6b434 100644 --- a/src/webassembly/expose-method.md +++ b/src/webassembly/expose-method.md @@ -24,6 +24,6 @@ pub fn add(a: i32, b: i32) -> i32 {
-* `set_panic_hook` is a convenient setup method that adds debug information to stack traces when a WASM module panics. Don't use it in prod builds because it is rather +* `set_panic_hook` is a convenient setup method that adds debug information to stack traces when a Wasm module panics. Don't use it in prod builds because it is rather
\ No newline at end of file diff --git a/src/webassembly/import-method.md b/src/webassembly/import-method.md index a732e3e4..5a455df5 100644 --- a/src/webassembly/import-method.md +++ b/src/webassembly/import-method.md @@ -1,6 +1,6 @@ # Import a Javascript method -Since WASM runs in the browser, we will want to interact directly with Javascript APIs from Rust. +Since Wasm runs in the browser, we will want to interact directly with Javascript APIs from Rust. For instance `println!` will not log to the javascript console, so we need to use `console.log`. Similarly, we want to be able to call `alert`. This works the same way as FFIs with C. diff --git a/src/webassembly/limitations.md b/src/webassembly/limitations.md index e54a0ad1..238ce3d7 100644 --- a/src/webassembly/limitations.md +++ b/src/webassembly/limitations.md @@ -2,7 +2,7 @@ Because it runs in a Virtual Machine with its own set of restrictions, some common native operations are not available in WebAssembly. For instance, -there is no file system in WASM, therefore file operations are handled +there is no file system in Wasm, therefore file operations are handled through Web APIs. Other methods from the standard library that rely on system calls cannot be @@ -10,20 +10,20 @@ used as well. They can however either be replaced by a dependency or be enabled by setting a feature flag. For instance, - Many methods from `std::time` rely on system calls, so they will panic when called -in WASM. [Drop in replacements](https://docs.rs/web-time/latest/web_time/) exist that +in Wasm. [Drop in replacements](https://docs.rs/web-time/latest/web_time/) exist that use the brower's `Date` and `performance` methods - `rand` which usually relies on thread local storage, can be made to use `Math.random()` by setting the dependency feature `getrandom = { ..., features = ["js"] }` - Statically linking against another language and bundling as one binary is mostly not supported -because the standard WASM ABI is not based on C's like in most environments. Instead, you +because the standard Wasm ABI is not based on C's like in most environments. Instead, you should dynamically link with `#[wasm_bindgen] extern "C"`. This means that some crates -which bundle C or C++ binaries will not be portable to WASM. +which bundle C or C++ binaries will not be portable to Wasm. Furthermore, interoperability with Javascript, a language that knows nothing about the borrow-checker but uses Garbage Collection to manage memory forces us to alter how we use both Rust and Javascript with WebAssembly. -This chapter covers a few caveats of WASM programming: +This chapter covers a few caveats of Wasm programming: - [Borrow Checker](limitations/borrow-checker.md) - [Closures](limitations/closures.md) diff --git a/src/webassembly/limitations/closures.md b/src/webassembly/limitations/closures.md index 83642e9b..a2366202 100644 --- a/src/webassembly/limitations/closures.md +++ b/src/webassembly/limitations/closures.md @@ -1,6 +1,6 @@ # Closures -Closures can be returned to Rust and executed on the WASM runtime. +Closures can be returned to Rust and executed on the Wasm runtime. ```rust use wasm_bindgen::prelude::*; @@ -46,7 +46,7 @@ import init, {set_panic_hook, timeout_set_seconds} from '/wasm/project.js'; * Since the function that creates the closure keeps its ownership, the closure would be dropped if we did't return it. * Returning ownership allows the JS runtime to manage the lifetime of the closure and to collect it when it can. * Try returning nothing from the method. -* Closures can only be passed by reference to WASM functions. +* Closures can only be passed by reference to Wasm functions. * This is why we pass `&Closure` to `setInterval`. * This is also why we need to create `ClosureHandle` to return the closure. diff --git a/src/webassembly/load-wasm-module.md b/src/webassembly/load-wasm-module.md index 74bd1629..887f16ed 100644 --- a/src/webassembly/load-wasm-module.md +++ b/src/webassembly/load-wasm-module.md @@ -1,11 +1,11 @@ -# Load a WASM module +# Load a Wasm module ## Commands to run: -### Compile Rust lib to WASM +### Compile Rust lib to Wasm -You can compile the basic WASM library provided in [rust-wasm-template](https://github.com/google/comprehensive-rust/tree/main/src/rust-wasm-template) with this command: +You can compile the basic Wasm library provided in [rust-wasm-template](https://github.com/google/comprehensive-rust/tree/main/src/rust-wasm-template) with this command: ```shell cd src/rust-wasm-template @@ -53,7 +53,7 @@ import init, {add} from '/wasm/project.js'; // A typescript version is also gene (async () => { // Run the init method to initiate the WebAssembly module. await init(); - console.log('WASM output', add(1, 2)); + console.log('Wasm output', add(1, 2)); })(); ```