feat: add --panic-unwind flag to build and test commands (#1572)

Adds a new --panic-unwind option to `wasm-pack build` and `wasm-pack test`
that builds with `-Cpanic=unwind` instead of the default `panic=abort`.

When the flag is set, cargo is invoked via `+nightly` with
`-Z build-std=std,panic_unwind` and `RUSTFLAGS` is augmented with
`-Cpanic=unwind` (preserving any user-provided `RUSTFLAGS`). The nightly
toolchain, `rust-src` component, and nightly `wasm32-unknown-unknown`
target are auto-installed via `rustup` if not already present. The stable
rustc and wasm-target preflight checks are skipped when --panic-unwind is
set, since they are irrelevant for the nightly invocation.

This is a build-tool-level enabler: it produces a wasm artifact compiled
with unwinding semantics. The actual conversion of caught panics into
JavaScript exceptions is the responsibility of the consuming bindings layer
(e.g. wasm-bindgen's catch-unwind support).

Author: guybedford

docs/src/commands/build.md

@@ -138,6 +138,45 @@ example, to build the previous example using cargo's offline feature:
 wasm-pack build examples/js-hello-world --mode no-install -- --offline
 ```
 
+## Panic strategy
+
+By default, Rust panics in WebAssembly compile with `panic=abort`, which aborts
+the WebAssembly instance on panic. The `--panic-unwind` flag changes this so
+panics can be caught at FFI boundaries and converted to JavaScript exceptions
+by tools like [`wasm-bindgen`'s catch-unwind support][wbg-catch-unwind].
+
+```
+wasm-pack build --panic-unwind
+```
+
+This flag:
+
+- Invokes `cargo` with the **nightly** toolchain (`cargo +nightly build`).
+- Adds `-Z build-std=std,panic_unwind` to rebuild `std` with unwinding
+  support.
+- Sets `RUSTFLAGS=-Cpanic=unwind` (preserving any user-provided `RUSTFLAGS`).
+
+The first time you use `--panic-unwind`, `wasm-pack` will install any missing
+prerequisites via `rustup`:
+
+- The nightly toolchain
+- The `rust-src` component for nightly
+- The `wasm32-unknown-unknown` target for nightly
+
+If you are not using `rustup` you must install these prerequisites manually.
+See [Non-`rustup` setups][non-rustup].
+
+> **Note:** `wasm-pack` only handles producing the `.wasm`. The actual
+> "panic = recoverable JavaScript exception" behaviour requires runtime glue
+> from your bindings layer (e.g. `wasm-bindgen`'s catch-unwind feature). With
+> just `--panic-unwind` and no runtime glue, panics still terminate the
+> instance — they are merely *unwound* rather than *aborted*.
+
+`--panic-unwind` is also available for [`wasm-pack test`](./test.md).
+
+[wbg-catch-unwind]: https://wasm-bindgen.github.io/wasm-bindgen/reference/catch-unwind.html
+[non-rustup]: ../prerequisites/non-rustup-setups.md
+
 <hr style="font-size: 1.5em; margin-top: 2.5em"/>
 
 <sup id="footnote-0">0</sup> If you need to include additional assets in the pkg

docs/src/commands/test.md

@@ -39,6 +39,16 @@ Choose where to run your tests by passing in any combination of testing environm
 wasm-pack test --node --firefox --chrome --safari --headless
 ```
 
+## Panic strategy
+
+The `test` command accepts the `--panic-unwind` flag, which builds the test
+binary with `panic=unwind` via the nightly toolchain and `-Z build-std`. See
+the [`build` command's documentation](./build.md#panic-strategy) for details.
+
+```
+wasm-pack test --node --panic-unwind
+```
+
 ## Extra options
 
 The `test` command can pass extra options straight to `cargo test` even if they are not

src/build/mod.rs

@@ -80,12 +80,22 @@ pub fn cargo_build_wasm(
     profile: BuildProfile,
     extra_options: &[String],
     target_triple: &str,
+    panic_unwind: bool,
 ) -> Result<String> {
-    let msg = format!("{}Compiling to Wasm...", emoji::CYCLONE);
+    let msg = if panic_unwind {
+        format!("{}Compiling to Wasm (with panic=unwind)...", emoji::CYCLONE)
+    } else {
+        format!("{}Compiling to Wasm...", emoji::CYCLONE)
+    };
     PBAR.info(&msg);
 
     let mut cmd = Command::new("cargo");
-    cmd.current_dir(path).arg("build").arg("--lib");
+    cmd.current_dir(path);
+    // `+nightly` must be the first argument to cargo.
+    if panic_unwind {
+        cmd.arg("+nightly");
+    }
+    cmd.arg("build").arg("--lib");
 
     if PBAR.quiet() {
         cmd.arg("--quiet");
@@ -114,6 +124,19 @@ pub fn cargo_build_wasm(
 
     cmd.env("CARGO_BUILD_TARGET", target_triple);
 
+    if panic_unwind {
+        cmd.arg("-Z").arg("build-std=std,panic_unwind");
+
+        // Append `-Cpanic=unwind` to any user-provided RUSTFLAGS.
+        let existing = std::env::var("RUSTFLAGS").unwrap_or_default();
+        let combined = if existing.is_empty() {
+            "-Cpanic=unwind".to_string()
+        } else {
+            format!("{existing} -Cpanic=unwind")
+        };
+        cmd.env("RUSTFLAGS", combined);
+    }
+
     // The `cargo` command is executed inside the directory at `path`, so relative paths set via extra options won't work.
     // To remedy the situation, all detected paths are converted to absolute paths.
     let mut handle_path = false;
@@ -191,15 +214,24 @@ pub fn cargo_build_wasm(
 /// * `path`: Path to the crate directory to build tests.
 /// * `debug`: Whether to build tests in `debug` mode.
 /// * `extra_options`: Additional parameters to pass to `cargo` when building tests.
+/// * `target_triple`: The wasm target triple to build for (e.g.
+///   `wasm32-unknown-unknown` or `wasm64-unknown-unknown`).
+/// * `panic_unwind`: Whether to build tests with `panic=unwind` via the nightly
+///   toolchain and `-Z build-std`.
 pub fn cargo_build_wasm_tests(
     path: &Path,
     debug: bool,
     extra_options: &[String],
     target_triple: &str,
+    panic_unwind: bool,
 ) -> Result<()> {
     let mut cmd = Command::new("cargo");
-
-    cmd.current_dir(path).arg("build").arg("--tests");
+    cmd.current_dir(path);
+    // `+nightly` must be the first argument to cargo.
+    if panic_unwind {
+        cmd.arg("+nightly");
+    }
+    cmd.arg("build").arg("--tests");
 
     if PBAR.quiet() {
         cmd.arg("--quiet");
@@ -211,6 +243,18 @@ pub fn cargo_build_wasm_tests(
 
     cmd.env("CARGO_BUILD_TARGET", target_triple);
 
+    if panic_unwind {
+        cmd.arg("-Z").arg("build-std=std,panic_unwind");
+
+        let existing = std::env::var("RUSTFLAGS").unwrap_or_default();
+        let combined = if existing.is_empty() {
+            "-Cpanic=unwind".to_string()
+        } else {
+            format!("{existing} -Cpanic=unwind")
+        };
+        cmd.env("RUSTFLAGS", combined);
+    }
+
     cmd.args(extra_options);
 
     child::run(cmd, "cargo build").context("Compilation of your program failed")?;

src/build/wasm_target.rs

@@ -160,3 +160,136 @@ fn rustup_add_wasm_target(target: &str) -> Result<()> {
 
     Ok(())
 }
+
+const NIGHTLY_TOOLCHAIN: &str = "nightly";
+
+/// Ensure that the nightly toolchain is installed and has the `rust-src`
+/// component and `wasm32-unknown-unknown` target, all of which are required
+/// for `-Z build-std` (used by `--panic-unwind`). Missing components are
+/// installed automatically via `rustup`.
+pub fn check_nightly_prerequisites() -> Result<()> {
+    let msg = format!(
+        "{}Checking nightly toolchain prerequisites for panic=unwind...",
+        emoji::TARGET
+    );
+    PBAR.info(&msg);
+
+    let nightly_sysroot = get_nightly_sysroot()?;
+    if !nightly_sysroot.exists() {
+        install_nightly_toolchain()?;
+    }
+
+    if !has_rust_src_component()? {
+        install_rust_src_component()?;
+    }
+
+    if !does_nightly_wasm32_target_exist() {
+        rustup_add_wasm_target_nightly()?;
+    }
+
+    Ok(())
+}
+
+fn get_nightly_sysroot() -> Result<PathBuf> {
+    let command = Command::new("rustc")
+        .args(["+nightly", "--print", "sysroot"])
+        .output()?;
+
+    if command.status.success() {
+        Ok(String::from_utf8(command.stdout)?.trim().into())
+    } else {
+        Err(anyhow!(
+            "Getting nightly rustc's sysroot wasn't successful. Got {}",
+            command.status
+        ))
+    }
+}
+
+fn install_nightly_toolchain() -> Result<()> {
+    let msg = format!(
+        "{}Installing nightly toolchain via rustup...",
+        emoji::TARGET
+    );
+    PBAR.info(&msg);
+
+    let mut cmd = Command::new("rustup");
+    cmd.arg("toolchain").arg("install").arg(NIGHTLY_TOOLCHAIN);
+    child::run(cmd, "rustup").context("Installing the nightly toolchain with rustup")?;
+
+    Ok(())
+}
+
+fn has_rust_src_component() -> Result<bool> {
+    let command = Command::new("rustup")
+        .args(["component", "list", "--toolchain", NIGHTLY_TOOLCHAIN])
+        .output()?;
+
+    if !command.status.success() {
+        return Ok(false);
+    }
+
+    let stdout = String::from_utf8(command.stdout)?;
+    Ok(stdout
+        .lines()
+        .any(|line| line.starts_with("rust-src") && line.contains("(installed)")))
+}
+
+fn install_rust_src_component() -> Result<()> {
+    let msg = format!(
+        "{}Installing rust-src component for nightly toolchain...",
+        emoji::TARGET
+    );
+    PBAR.info(&msg);
+
+    let mut cmd = Command::new("rustup");
+    cmd.arg("component")
+        .arg("add")
+        .arg("rust-src")
+        .arg("--toolchain")
+        .arg(NIGHTLY_TOOLCHAIN);
+    child::run(cmd, "rustup").context("Adding the rust-src component with rustup")?;
+
+    Ok(())
+}
+
+fn does_nightly_wasm32_target_exist() -> bool {
+    let command = Command::new("rustc")
+        .args([
+            "+nightly",
+            "--target",
+            "wasm32-unknown-unknown",
+            "--print",
+            "target-libdir",
+        ])
+        .output();
+
+    match command {
+        Ok(output) if output.status.success() => {
+            let path: PathBuf = String::from_utf8(output.stdout)
+                .ok()
+                .map(|s| s.trim().into())
+                .unwrap_or_default();
+            path.exists()
+        }
+        _ => false,
+    }
+}
+
+fn rustup_add_wasm_target_nightly() -> Result<()> {
+    let msg = format!(
+        "{}Adding wasm32-unknown-unknown target for nightly toolchain...",
+        emoji::TARGET
+    );
+    PBAR.info(&msg);
+
+    let mut cmd = Command::new("rustup");
+    cmd.arg("target")
+        .arg("add")
+        .arg("wasm32-unknown-unknown")
+        .arg("--toolchain")
+        .arg(NIGHTLY_TOOLCHAIN);
+    child::run(cmd, "rustup")
+        .context("Adding the wasm32-unknown-unknown target for nightly with rustup")?;
+
+    Ok(())
+}

src/command/build.rs

@@ -41,6 +41,7 @@ pub struct Build {
     pub bindgen: Option<install::Status>,
     pub cache: Cache,
     pub extra_options: Vec<String>,
+    pub panic_unwind: bool,
     target_triple: String,
     wasm_path: Option<String>,
 }
@@ -184,6 +185,15 @@ pub struct BuildOptions {
     /// Option to skip optimization with wasm-opt
     pub no_opt: bool,
 
+    #[clap(long = "panic-unwind")]
+    /// Build with panic=unwind. Requires the nightly Rust toolchain; uses
+    /// `-Z build-std` to rebuild `std` with `-Cpanic=unwind` so panics can be
+    /// caught at FFI boundaries instead of aborting the WebAssembly instance.
+    /// The nightly toolchain, `rust-src` component, and nightly
+    /// `wasm32-unknown-unknown` target will be installed via `rustup` if not
+    /// already present.
+    pub panic_unwind: bool,
+
     /// List of extra options to pass to `cargo build`
     pub extra_options: Vec<String>,
 }
@@ -207,6 +217,7 @@ impl Default for BuildOptions {
             profile: None,
             out_dir: String::new(),
             out_name: None,
+            panic_unwind: false,
             extra_options: Vec::new(),
         }
     }
@@ -278,6 +289,7 @@ impl Build {
             cache: cache::get_wasm_pack_cache()?,
             target_triple: target_triple.to_owned(),
             extra_options,
+            panic_unwind: build_opts.panic_unwind,
             wasm_path: None,
         })
     }
@@ -364,6 +376,12 @@ impl Build {
     }
 
     fn step_check_rustc_version(&mut self) -> Result<()> {
+        // The stable rustc version is irrelevant when --panic-unwind is set,
+        // since cargo will be invoked via `+nightly`.
+        if self.panic_unwind {
+            info!("Skipping rustc version check (using nightly via --panic-unwind).");
+            return Ok(());
+        }
         info!("Checking rustc version...");
         let version = build::check_rustc_version()?;
         let msg = format!("rustc version is {}.", version);
@@ -379,6 +397,12 @@ impl Build {
     }
 
     fn step_check_for_wasm_target(&mut self) -> Result<()> {
+        if self.panic_unwind {
+            info!("Checking nightly toolchain prerequisites for panic=unwind...");
+            build::wasm_target::check_nightly_prerequisites()?;
+            info!("Nightly prerequisites check was successful.");
+            return Ok(());
+        }
         info!("Checking for wasm-target...");
         build::wasm_target::check_for_wasm_target(&self.target_triple)?;
         info!("Checking for wasm-target was successful.");
@@ -392,6 +416,7 @@ impl Build {
             self.profile.clone(),
             &self.extra_options,
             &self.target_triple,
+            self.panic_unwind,
         )?;
         info!("wasm built at {wasm_path:#?}.");
         self.wasm_path = Some(wasm_path);