src/utils.rs - Hello wasm-pack! (original) (raw)

1. 1. Introduction
2. 2. Quickstart
3. 3. Prerequisites
4. 1. 3.1. npm (optional)
   2. 3.2. considerations
   3. 3.3. Non-rustup setups
5. 4. Commands
6. 1. 4.1. new
   2. 4.2. build
   3. 4.3. test
   4. 4.4. pack and publish
   5. 4.5. init (DEPRECATED)
7. 5. Tutorials
8. 1. 5.1. Hybrid applications with Webpack
   2. 1. 5.1.1. Getting started
         1. 5.1.2. Using your library
   3. 5.2. npm browser packages
   4. 1. 5.2.1. Getting started
         1. 1. 5.2.1.1. Manual Setup
         2. 5.2.2. Template deep dive
         3. 1. 5.2.2.1. Cargo.toml
               1. 5.2.2.2. src/lib.rs
               2. 5.2.2.3. src/utils.rs
               3. 5.2.2.4. wee_alloc
               4. 5.2.2.5. tests/web.rs
         4. 5.2.3. Building your project
         5. 5.2.4. Testing your project
         6. 5.2.5. Packaging and publishing
         7. 5.2.6. Using your library
9. 6. Cargo.toml Configuration
10. 7. Contributing

This documentation isno longer maintained at this domain, and is now maintained at drager.github.io/wasm-pack instead.

Hello wasm-pack!

src/utils.rs

The purpose of utils.rs is to define the utils module, which contains a single function set_panic_hook. This function becomes part of the utils module in lib.rs, as described in the preceding section.

If the console_error_panic_hook feature is not enabled, then set_panic_hook is defined to be an inlined empty function. So, there is no run-time performance or code-size penalty incurred by its use.

We will discuss:

1. Defining set_panic_hook
2. What is console_error_panic_hook?

1. Defining set_panic_hook

# #![allow(unused_variables)]
#fn main() {
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();
}
#}

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 theconsole_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?

The crate console_error_panic_hook allows debugging Rust panic messages in a web browser, making it much easier to debug WebAssembly code.

Let's compare what happens when Rust code panics before and after enabling the feature:

Before: "RuntimeError: Unreachable executed"

After: "panicked at 'index out of bounds: the len is 3 but the index is 4', libcore/slice/mod.rs:2046:10"

To do this, a panic hook is configured that logs panics to the developer console via the JavaScript console.error function.

Note though that console_error_panic_hook is not entirely automatic, so you'll need to make sure that utils::set_panic_hook() is called before any of our code runs (and it's safe to run set_panic_hook many times).

For more details, see the console_error_panic_hookrepository.