diff --git a/Cargo.toml b/Cargo.toml index 33322a04..cbf45638 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -23,6 +23,10 @@ std = [] # i.e. avoid unconditionally enabling it in library crates. wasm_js = ["dep:wasm-bindgen", "dep:js-sys"] +# 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. +assume_wasm_js = ["wasm_js"] + [dependencies] cfg-if = "1" diff --git a/README.md b/README.md index 17e84860..ea61e665 100644 --- a/README.md +++ b/README.md @@ -130,22 +130,26 @@ 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). +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. + 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]). - -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. +one of the following: + +- Use the `wasm_js` feature flag to enable the backend, **and** + set `RUSTFLAGS='--cfg getrandom_backend="wasm_js"'` to select this backend + ([see above][opt-in]). +- Use the `assume_wasm_js` feature flag: + `getrandom = { version = "0.4", features = ["assume_wasm_js"] }`. + This enables `wasm_js` and uses the backend by default on `wasm32` with + unknown OS. + +WARNING: enabling the `wasm_js` or `assume_wasm_js` feature will bloat +`Cargo.lock` on all platforms (where [`wasm-bindgen`] is not an existing +dependency) and may cause build issues on non-web WASM platforms. ### Custom backend diff --git a/src/backends.rs b/src/backends.rs index d7b73cec..ae4f3b3a 100644 --- a/src/backends.rs +++ b/src/backends.rs @@ -28,7 +28,7 @@ cfg_if! { } else if #[cfg(getrandom_backend = "efi_rng")] { mod efi_rng; pub use efi_rng::*; - } 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; @@ -183,13 +183,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 = "assume_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: \