From 2c2627d3202335f886f4b66d9b5356449cac1ac3 Mon Sep 17 00:00:00 2001 From: Ashley Williams Date: Mon, 1 Apr 2019 11:37:45 -0500 Subject: [PATCH 1/8] feat(ci): print mdbook version --- .travis.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.travis.yml b/.travis.yml index 0d747fbc..2de24c4b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -62,6 +62,7 @@ matrix: - (test -x $HOME/.cargo/bin/mdbook || cargo install --vers "^0.2" mdbook) - cargo install-update -a script: + - mdbook --version - (cd docs && mv _theme theme && mdbook build) - rustc ./docs/_installer/build-installer.rs - ./build-installer From 305f0513ead8d232b8f40e7d967e0564ed002d5e Mon Sep 17 00:00:00 2001 From: Ashley Williams Date: Mon, 1 Apr 2019 12:22:44 -0500 Subject: [PATCH 2/8] fix(docs): links and update to no cfg_if template --- docs/src/prerequisites/index.md | 2 +- .../hybrid-applications-with-webpack/index.md | 2 +- .../tutorials/npm-browser-packages/index.md | 7 +-- .../template-deep-dive/cargo-toml.md | 12 ++-- .../template-deep-dive/src-lib-rs.md | 57 +++++++++---------- .../template-deep-dive/src-utils-rs.md | 50 +++++----------- 6 files changed, 47 insertions(+), 83 deletions(-) diff --git a/docs/src/prerequisites/index.md b/docs/src/prerequisites/index.md index 1d295d6d..f2e27138 100644 --- a/docs/src/prerequisites/index.md +++ b/docs/src/prerequisites/index.md @@ -18,4 +18,4 @@ involved! [npm]: prerequisites/npm.html -Using a non-rustup setup? Learn how to configure it for wasm-pack [here](./non-rustup-setups.html). +Using a non-rustup setup? Learn how to configure it for wasm-pack [here](prerequisites/non-rustup-setups.html). diff --git a/docs/src/tutorials/hybrid-applications-with-webpack/index.md b/docs/src/tutorials/hybrid-applications-with-webpack/index.md index 987191b0..06f006f7 100644 --- a/docs/src/tutorials/hybrid-applications-with-webpack/index.md +++ b/docs/src/tutorials/hybrid-applications-with-webpack/index.md @@ -6,7 +6,7 @@ and the `wasm-pack` workflow by building the example app in the template. This tutorial is aimed at folks who are both beginners to WebAssembly and Rust- you don't need much Rust knowledge to complete this tutorial. -Be sure to have read and followed the [Prerequisites](../prerequisites/index.html). +Be sure to have read and followed the [Prerequisites](../../../prerequisites/index.html). [Rust]: https://www.rust-lang.org [Node.js]: https://nodejs.org diff --git a/docs/src/tutorials/npm-browser-packages/index.md b/docs/src/tutorials/npm-browser-packages/index.md index 4bd69ca9..c38f461e 100644 --- a/docs/src/tutorials/npm-browser-packages/index.md +++ b/docs/src/tutorials/npm-browser-packages/index.md @@ -8,11 +8,8 @@ much Rust knowledge to complete this tutorial. Be sure to have done the following before starting: -1. [Install `wasm-pack`](../../installer) -1. Read and install the [Prerequisites](../prerequisites/index.html). - - - You'll need [Rust], version 1.30 or higher. (Currently either `beta` or `nightly` channels). [Learn more](../prerequisites/rust.html). - - You'll need [Node.js] and [npm] installed. You'll also need an npm Account. [Learn more](../prerequisites/npm.html). +1. [Install `wasm-pack`](https://rustwasm.github.io/wasm-pack/installer/) +1. Read and install the [Prerequisites](../../../prerequisites/index.html). ⚠️ We strongly recommend that you install [Node.js] using a version manager. You can learn more [here](https://npmjs.com/get-npm). diff --git a/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md b/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md index d7e6f172..50c86bbc 100644 --- a/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md +++ b/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md @@ -67,7 +67,6 @@ However, that's not the case! In Rust, the `^` is implied. You can read more abo [`wee_alloc`]: https://crates.io/crates/wee_alloc [`console_error_panic_hook`]: https://crates.io/crates/console_error_panic_hook -[`cfg-if`]: https://crates.io/crates/cfg-if As part of our effort to design a template that helps people discover useful crates for their particular use case, this template includes two dependencies that can be @@ -83,7 +82,6 @@ them both as dependencies, but also allows them to be optionally included. default = ["console_error_panic_hook"] [dependencies] -cfg-if = "0.1.2" wasm-bindgen = "0.2" # The `console_error_panic_hook` crate provides better debugging of panics by @@ -100,12 +98,10 @@ console_error_panic_hook = { version = "0.1.1", optional = true } wee_alloc = { version = "0.4.2", optional = true } ``` -[`cfg-if`] allows us to check if certain features are enabled on a Rust crate. We'll -use this crate later to optionally enable [`console_error_panic_hook` or -`wee_alloc`. - -By default, only `console_error_panic_hook` is enabled. To disable either -feature, we can remove its name from the `default` vector. +In our code, we'll mark certain parts of code as running only if certain `[features]` +are enabled, specifically, `console_error_panic_hook` and `weealloc`. By default, +only `console_error_panic_hook` is enabled. To disable or enable either feature, by +default, we can edit the `default` vector under `[features]`. To learn more about these features, we discuss them in-depth in the [`src/lib.rs`] and [`src/utils.rs`] sections. diff --git a/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md b/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md index df36e4b9..93e81a4e 100644 --- a/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md +++ b/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md @@ -13,6 +13,25 @@ It contains three key parts: We'll start with the most important part of `lib.rs` -- the two `#[wasm_bindgen]` functions (which you can find at the bottom of the file). In many cases, this is the only part of `lib.rs` you will need to modify. +## 1. Using `wasm_bindgen` + +To expose functionality from the `wasm-bindgen` crate more conveniently we can use the `use` keyword. +`use` allows us to conveniently refer to parts of a crate or module. You can learn more about how Rust +lets you write modular code in [this chapter of the book](https://doc.rust-lang.org/book/ch07-02-modules-and-use-to-control-scope-and-privacy.html). + +```rust +use wasm_bindgen::prelude::*; +``` + +Many crates contain a prelude, a list of things that are convenient to import +all at once. This allows common features of the module to be conveniently +accessed without a lengthy prefix. For example, in this file we can use +`#[wasm_bindgen]` only because it is brought into scope by the prelude. + +The asterisk at the end of this `use` indicates that everything inside the module `wasm_bindgen::prelude` (i.e. the module `prelude` inside the crate `wasm_bindgen`) can be referred to without prefixing it with `wasm_bindgen::prelude`. + +For example, `#[wasm_bindgen]` could also be written as `#[wasm_bindgen::prelude::wasm_bindgen]`, although this is not recommended. + ## 1. `#[wasm_bindgen]` functions The `#[wasm_bindgen]` attribute indicates that the function below it will be accessible both in JavaScript and Rust. @@ -63,43 +82,19 @@ Either way, the contents of `utils.rs` define a single public function `set_pani ```rust -use cfg_if::cfg_if; +// When the `wee_alloc` feature is enabled, use `wee_alloc` as the global + // When the `wee_alloc` feature is enabled, use `wee_alloc` as the global // allocator. + // allocator. #[cfg(feature = "wee_alloc")] + if #[cfg(feature = "wee_alloc")] { #[global_allocator] + #[global_allocator] static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT; ``` -`use` allows us to conveniently refer to parts of a crate or module. For example, suppose the crate `cfg_if` contains a function `func`. It is always possible to call this function directly by writing `cfg_if::func()`. However, this is often tedious to write. If we first specify `use cfg_if::func;`, then `func` can be called by just writing `func()` instead. You can learn more about how Rust let's you -write modular code in [this chapter of the book](https://doc.rust-lang.org/book/ch07-02-modules-and-use-to-control-scope-and-privacy.html). - -With this in mind, this `use` allows us to call the macro `cfg_if!` inside the crate `cfg_if` without writing `cfg_if::cfg_if!`. We use `cfg_if!` to configure `wee_alloc`, which we will talk more about in a [separate section](./wee_alloc.md): - -```rust -cfg_if! { - if #[cfg(feature = "wee_alloc")] { - #[global_allocator] - static ALLOC: wee_alloc::WeeAlloc = wee_alloc::WeeAlloc::INIT; - } -} -``` - -We immediately notice that `cfg_if!` is a macro because it ends in `!`, similarly to other Rust macros such as `println!` and `vec!`. A macro is directly replaced by other code during compile time. - At compile time this will test if the `wee_alloc` feature is enabled for this compilation. If it's enabled we'll configure a global allocator (according to [`wee_alloc`'s docs][wee-alloc-docs]), otherwise it'll compile to nothing. [wee-alloc-docs]: https://docs.rs/wee_alloc/0.4.3/wee_alloc/ -As we saw earlier, the `default` vector in `[features]` only contains `"console_error_panic_hook"` and not `"wee_alloc"`. So, in this case, the `cfg_if!` block will be replaced by no code at all, and hence the default memory allocator will be used instead of `wee_alloc`. - -```rust -use wasm_bindgen::prelude::*; -``` - -Many crates contain a prelude, a list of things that are convenient to import -all at once. This allows common features of the module to be conveniently -accessed without a lengthy prefix. For example, in this file we can use -`#[wasm_bindgen]` only because it is brought into scope by the prelude. - -The asterisk at the end of this `use` indicates that everything inside the module `wasm_bindgen::prelude` (i.e. the module `prelude` inside the crate `wasm_bindgen`) can be referred to without prefixing it with `wasm_bindgen::prelude`. - -For example, `#[wasm_bindgen]` could also be written as `#[wasm_bindgen::prelude::wasm_bindgen]`, although this is not recommended. +As we saw earlier, the `default` vector in `[features]` only contains `"console_error_panic_hook"` and not `"wee_alloc"`. So, in this case, this +block will be replaced by no code at all, and hence the default memory allocator will be used instead of `wee_alloc`. diff --git a/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-utils-rs.md b/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-utils-rs.md index 92b05442..0c557d1e 100644 --- a/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-utils-rs.md +++ b/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-utils-rs.md @@ -14,46 +14,22 @@ We will discuss: ## 1. Defining `set_panic_hook` ```rust -use cfg_if::cfg_if; -``` - -This allows us to write `cfg_if!` instead of `cfg_if::cfg_if!`, identically to the line in `src/lib.rs`. - -```rust -cfg_if! { - if #[cfg(feature = "console_error_panic_hook")] { - pub use self::console_error_panic_hook::set_once as set_panic_hook; - } else { - #[inline] - pub fn set_panic_hook() {} - } +pub fn set_panic_hook() { + // When the `console_error_panic_hook` feature is enabled, we can call the + // `set_panic_hook` function at least once during initialization, and then + // we will get better error messages if our code ever panics. + // + // For more details see + // https://github.com/rustwasm/console_error_panic_hook#readme + #[cfg(feature = "console_error_panic_hook")] + console_error_panic_hook::set_once(); } ``` -As described in the preceding section, this invocation of the `cfg_if!` -tests whether the `console_error_panic_hook` feature is enabled at compile time, -replacing with the statements in the `if` block or with those in the `else` -block. These two cases are: - -```rust -pub use self::console_error_panic_hook::set_once as set_panic_hook; -``` - -This `use` statement means the function -`self::console_error_panic_hook::set_once` can now be accessed more conveniently -as `set_panic_hook`. With `pub`, this function will be accessible -outside of the `utils` module as `utils::set_panic_hook`. - -```rust -#[inline] -pub fn set_panic_hook() {} -``` - -Here, `set_panic_hook` is defined to be an empty inline function. The inline -annotation here means that whenever the function is called the function call is -replaced with the body of the function, which is for `set_panic_hook` nothing! -This allows the use of `set_panic_hook` without any run-time or code-size -performance penalty if the feature is not enabled. +Here, we define a function that's preceded by a `cfg` attribute. This attribue, +`#[cfg(feature = "console_error_panic_hook")]`, tells Rust to check if the +`console_error_panic_hook` feature is set at compile time. If it is, it will call +this function. If it isn't- it won't! ## 2. What is `console_error_panic_hook`? From 83433ddd38c57570b4ae92fa0f4d2dde5e3c39a1 Mon Sep 17 00:00:00 2001 From: Ashley Williams Date: Mon, 1 Apr 2019 15:38:19 -0500 Subject: [PATCH 3/8] fix(doc): remove npm link discussion as doc does not exist(yet) --- docs/src/prerequisites/npm.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/src/prerequisites/npm.md b/docs/src/prerequisites/npm.md index 16fe38dd..277b8d09 100644 --- a/docs/src/prerequisites/npm.md +++ b/docs/src/prerequisites/npm.md @@ -20,11 +20,6 @@ your package to the npm registry you'll need an npm account. You can find information about signing up for npm [here][npm-signup-info]. -If you'd rather not sign up for an account or publish a package to the regsitry, you can -use the [`npm link`] command to use your generated package locally, which we'll discuss -later in the [Tutorial]. - [`npm link`]: https://docs.npmjs.com/cli/link [npm-install-info]: https://www.npmjs.com/get-npm [npm-signup-info]: https://www.npmjs.com/signup -[Tutorial]: ../tutorial/index.html From cd5284b1ecd7eb89c7743b65835b3d9e0f7d798b Mon Sep 17 00:00:00 2001 From: Ashley Williams Date: Mon, 1 Apr 2019 15:39:54 -0500 Subject: [PATCH 4/8] fix(doc): s/tutorial/tutorials --- .../npm-browser-packages/getting-started/manual-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/tutorials/npm-browser-packages/getting-started/manual-setup.md b/docs/src/tutorials/npm-browser-packages/getting-started/manual-setup.md index 5c7167cc..15a06287 100644 --- a/docs/src/tutorials/npm-browser-packages/getting-started/manual-setup.md +++ b/docs/src/tutorials/npm-browser-packages/getting-started/manual-setup.md @@ -80,7 +80,7 @@ pub fn greet() { } ``` -And that's it! We'll talk about what this code does in the [Tutorial], which you are all +And that's it! We'll talk about what this code does in the [Tutorials], which you are all setup for now. Happy `wasm-pack`ing! -[Tutorial]: ../tutorial/index.html +[Tutorials]: ../tutorials/index.html From 49891974a397aed0f26c811d768948a2dd6195cf Mon Sep 17 00:00:00 2001 From: Ashley Williams Date: Mon, 1 Apr 2019 15:45:59 -0500 Subject: [PATCH 5/8] fix(docs): landing page with no relative links --- docs/src/SUMMARY.md | 1 + docs/src/introduction.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 docs/src/introduction.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index a2ced358..de7908b2 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,5 +1,6 @@ # Summary +- [Introduction](./introduction.md) - [Prerequisites](./prerequisites/index.md) - [npm (optional)](./prerequisites/npm.md) - [Non-`rustup` setups](./prerequisites/non-rustup-setups.md) diff --git a/docs/src/introduction.md b/docs/src/introduction.md new file mode 100644 index 00000000..23d15bea --- /dev/null +++ b/docs/src/introduction.md @@ -0,0 +1,3 @@ +![wasm ferris](https://rustwasm.github.io/wasm-pack/public/img/wasm-ferris.png) + +

Welcome to the wasm-pack docs!

From a4c9e2a3cdbfa8f0807b73f488e62df4baf898b7 Mon Sep 17 00:00:00 2001 From: Ashley Williams Date: Mon, 1 Apr 2019 15:51:33 -0500 Subject: [PATCH 6/8] feat(doc): add readme to docs landing page --- docs/src/introduction.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/src/introduction.md b/docs/src/introduction.md index 23d15bea..b00dd121 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,3 +1,21 @@ ![wasm ferris](https://rustwasm.github.io/wasm-pack/public/img/wasm-ferris.png)

Welcome to the wasm-pack docs!

+ +This tool seeks to be a one-stop shop for building and working with rust- +generated WebAssembly that you would like to interop with JavaScript, in the +browser or with Node.js. `wasm-pack` helps you build rust-generated +WebAssembly packages that you could publish to the npm registry, or otherwise use +alongside any javascript packages in workflows that you already use, such as [webpack] +or [greenkeeper]. + +[bundler-support]: https://github.com/rustwasm/team/blob/master/goals/bundler-integration.md#details +[webpack]: https://webpack.js.org/ +[greenkeeper]: https://greenkeeper.io/ + +This project is a part of the [rust-wasm] group. You can find more info by +visiting that repo! + +[rust-wasm]: https://github.com/rustwasm/team + +![demo](https://github.com/rustwasm/wasm-pack/raw/master/demo.gif) From 3a4b7f08f365ba2f5b9dd7b53f5faae656dccd05 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Mon, 1 Apr 2019 16:07:27 -0500 Subject: [PATCH 7/8] Update docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md Co-Authored-By: ashleygwilliams --- .../npm-browser-packages/template-deep-dive/cargo-toml.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md b/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md index 50c86bbc..3c86d851 100644 --- a/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md +++ b/docs/src/tutorials/npm-browser-packages/template-deep-dive/cargo-toml.md @@ -99,7 +99,7 @@ wee_alloc = { version = "0.4.2", optional = true } ``` In our code, we'll mark certain parts of code as running only if certain `[features]` -are enabled, specifically, `console_error_panic_hook` and `weealloc`. By default, +are enabled, specifically, `console_error_panic_hook` and `wee_alloc`. By default, only `console_error_panic_hook` is enabled. To disable or enable either feature, by default, we can edit the `default` vector under `[features]`. From d73ab9d143cdf43d91b55856d68fb1328487bcd7 Mon Sep 17 00:00:00 2001 From: Nick Fitzgerald Date: Mon, 1 Apr 2019 16:07:41 -0500 Subject: [PATCH 8/8] Update docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md Co-Authored-By: ashleygwilliams --- .../npm-browser-packages/template-deep-dive/src-lib-rs.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md b/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md index 93e81a4e..1a0624a8 100644 --- a/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md +++ b/docs/src/tutorials/npm-browser-packages/template-deep-dive/src-lib-rs.md @@ -82,7 +82,7 @@ Either way, the contents of `utils.rs` define a single public function `set_pani ```rust -// When the `wee_alloc` feature is enabled, use `wee_alloc` as the global + // When the `wee_alloc` feature is enabled, use `wee_alloc` as the global // When the `wee_alloc` feature is enabled, use `wee_alloc` as the global // allocator. // allocator. #[cfg(feature = "wee_alloc")] if #[cfg(feature = "wee_alloc")] { #[global_allocator]