Implement #675: let wasm_js enable the backend by default (#730)

Implements #675. Closes #726.

Now, when the `wasm_js` feature is enabled and `getrandom_backend` is not specified, this crate will use the `wasm_js` implementation by default (instead of failing to compile).

The backend my still be overridden via `getrandom_backend` as with any other platform.

Author: dhardy

Cargo.toml

@@ -17,8 +17,8 @@ exclude = [".*"]
 std = []
 
 # Optional backend: wasm_js
-# This flag enables the backend but does not select it. To use the backend, use
-# this flag *and* set getrandom_backend=wasm_js (see README).
+# This flag enables the wasm_js backend and uses it by default on wasm32 where
+# the target_os is unknown. The getrandom_backend cfg may override this.
 # WARNING: It is highly recommended to enable this feature only for binary crates and tests,
 # i.e. avoid unconditionally enabling it in library crates.
 wasm_js = ["dep:wasm-bindgen", "dep:js-sys"]

README.md

@@ -131,22 +131,20 @@ the `wasm32-unknown-unknown` target (i.e. the target used by `wasm-pack`)
 is not automatically supported since, from the target name alone, we cannot deduce
 which JavaScript interface should be used (or if JavaScript is available at all).
 
-To enable `getrandom`'s functionality on `wasm32-unknown-unknown` using the Web
-Crypto methods [described above][opt-in] via [`wasm-bindgen`], do
-*both* of the following:
-
--   Use the `wasm_js` feature flag, i.e.
-    `getrandom = { version = "0.3", features = ["wasm_js"] }`.
-    On its own, this only makes the backend available. (As a side effect this
-    will make your `Cargo.lock` significantly larger if you are not already
-    using [`wasm-bindgen`], but otherwise enabling this feature is harmless.)
--   Set `RUSTFLAGS='--cfg getrandom_backend="wasm_js"'` ([see above][opt-in]).
+We do not include support for this target in the default configuration because
+our JS backend (supporting web browsers, web workers and Node.js v19 or later)
+requires [`wasm-bindgen`], **bloating `Cargo.lock`** and
+**potentially breaking builds** on non-web WASM platforms.
 
-This backend supports both web browsers (main window and Web Workers)
-and Node.js (v19 or later) environments.
-
-WARNING: It is highly recommended to enable the `wasm_js` feature only for
-binary crates and tests, i.e. avoid unconditionally enabling it in library crates.
+To enable `getrandom`'s functionality on `wasm32-unknown-unknown` using the Web
+Crypto methods [described above][opt-in] via [`wasm-bindgen`], enable the
+`wasm_js` feature flag. Optionally, one can also set
+`RUSTFLAGS='--cfg getrandom_backend="wasm_js"'`.
+
+WARNING: enabling the `wasm_js` feature will bloat `Cargo.lock` on all platforms
+(where [`wasm-bindgen`] is not an existing dependency) and is known to cause
+build issues on some non-web WASM platforms, even when a different backend is
+selected via `getrandom_backend`.
 
 ### Custom backend
 

src/backends.rs

@@ -31,7 +31,7 @@ cfg_if! {
     } else if #[cfg(getrandom_backend = "windows_legacy")] {
         mod windows_legacy;
         pub use windows_legacy::*;
-    } else if #[cfg(all(getrandom_backend = "wasm_js"))] {
+    } else if #[cfg(getrandom_backend = "wasm_js")] {
         cfg_if! {
             if #[cfg(feature = "wasm_js")] {
                 mod wasm_js;
@@ -186,13 +186,20 @@ cfg_if! {
         mod rdrand;
         pub use rdrand::*;
     } else if #[cfg(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none")))] {
-        compile_error!(concat!(
-            "The wasm32-unknown-unknown targets are not supported by default; \
-            you may need to enable the \"wasm_js\" configuration flag. Note \
-            that enabling the `wasm_js` feature flag alone is insufficient. \
-            For more information see: \
-            https://docs.rs/getrandom/", env!("CARGO_PKG_VERSION"), "/#webassembly-support"
-        ));
+        cfg_if! {
+            if #[cfg(feature = "wasm_js")] {
+                mod wasm_js;
+                pub use wasm_js::*;
+            } else {
+                compile_error!(concat!(
+                    "The wasm32-unknown-unknown targets are not supported by default; \
+                    you may need to enable the \"wasm_js\" configuration flag. Note \
+                    that enabling the `wasm_js` feature flag alone is insufficient. \
+                    For more information see: \
+                    https://docs.rs/getrandom/", env!("CARGO_PKG_VERSION"), "/#webassembly-support"
+                ));
+            }
+        }
     } else {
         compile_error!(concat!(
             "target is not supported. You may need to define a custom backend see: \