diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 5c340c33..707ac362 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -142,8 +142,8 @@ jobs: { description: WasmV1, target: wasm32v1-none }, ] feature: [ - { description: no_std, feature: "--features js", build-std: "core,alloc", std: false }, - { feature: "--features js,std", build-std: "panic_abort,std", std: true }, + { description: no_std, feature: "--features wasm_js", build-std: "core,alloc", std: false }, + { feature: "--features wasm_js,std", build-std: "panic_abort,std", std: true }, ] atomic: [ { flags: "" }, diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index c03495bd..57cf9e87 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -237,14 +237,14 @@ jobs: - { description: Web, version: stable, - args: '--features=std,js', + args: '--features=std,wasm_js', } - { description: Web with Atomics, version: nightly, components: rust-src, flags: '-Dwarnings --cfg getrandom_backend="wasm_js" -Ctarget-feature=+atomics,+bulk-memory', - args: '--features=std,js -Zbuild-std=panic_abort,std', + args: '--features=std,wasm_js -Zbuild-std=panic_abort,std', } steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 994db90e..14b37dd9 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -48,11 +48,11 @@ jobs: - name: Web WASM (wasm_js.rs) env: RUSTFLAGS: -Dwarnings --cfg getrandom_backend="wasm_js" - run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features js + run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features wasm_js - name: Web WASM with atomics (wasm_js.rs) env: RUSTFLAGS: -Dwarnings --cfg getrandom_backend="wasm_js" -Ctarget-feature=+atomics,+bulk-memory - run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features js + run: cargo clippy -Zbuild-std --target wasm32-unknown-unknown --features wasm_js - name: Linux (linux_android.rs) env: RUSTFLAGS: -Dwarnings --cfg getrandom_backend="linux_getrandom" diff --git a/Cargo.toml b/Cargo.toml index 4c795c23..8e6d0e6a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,9 +19,9 @@ std = [] rustc-dep-of-std = ["dep:compiler_builtins", "dep:core"] # Optional backend: wasm_js -# This flag enables the backend and uses it by default on wasm32 with unknown OS. -# The backend may still be overridden by setting getrandom_backend. -js = ["dep:wasm-bindgen", "dep:js-sys"] +# 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). +wasm_js = ["dep:wasm-bindgen", "dep:js-sys"] [dependencies] cfg-if = "1" diff --git a/README.md b/README.md index 6e7e3e28..0007634c 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ of randomness based on their specific needs: | `linux_getrandom` | Linux, Android | `*‑linux‑*` | [`getrandom`][1] system call (without `/dev/urandom` fallback). Bumps minimum supported Linux kernel version to 3.17 and Android API level to 23 (Marshmallow). | `rdrand` | x86, x86-64 | `x86_64-*`, `i686-*` | [`RDRAND`] instruction | `rndr` | AArch64 | `aarch64-*` | [`RNDR`] register -| `wasm_js` | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]. Requires feature `js`. +| `wasm_js` | Web Browser, Node.js | `wasm32‑unknown‑unknown`, `wasm32v1-none` | [`Crypto.getRandomValues`]. Requires feature `wasm_js` ([see below](#webassembly-support)). | `custom` | All targets | `*` | User-provided custom implementation (see [custom backend]) Opt-in backends can be enabled using the `getrandom_backend` configuration flag. @@ -112,19 +112,19 @@ 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). -Instead, *if the `js` feature is enabled*, this crate will assume -that you are building for an environment containing JavaScript, and will -call the appropriate Web Crypto methods [described above](#opt-in-backends) using -the [`wasm-bindgen`] toolchain (with or without using `getrandom_backend=wasm_js`). -Both web browser (main window and Web Workers) -and Node.js (v19 or later) environments are supported. +To enable `getrandom`'s functionality on `wasm32-unknown-unknown` using the Web +Crypto methods [described above](#opt-in-backends) via [`wasm-bindgen`], do +*both* of the following: -To enable the `wasm_js` backend, you can add the following lines to your -project's `.cargo/config.toml` file: -```toml -[dependencies] -getrandom = { version = "0.3", features = ["js"] } -``` +- 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-backends)). + +This backend supports both web browsers (main window and Web Workers) +and Node.js (v19 or later) environments. ### Custom backend diff --git a/src/backends.rs b/src/backends.rs index 7abb8d3f..fd360b31 100644 --- a/src/backends.rs +++ b/src/backends.rs @@ -19,7 +19,7 @@ cfg_if! { } else if #[cfg(getrandom_backend = "rndr")] { mod rndr; pub use rndr::*; - } else if #[cfg(all(feature = "js", getrandom_backend = "wasm_js"))] { + } else if #[cfg(all(feature = "wasm_js", getrandom_backend = "wasm_js"))] { mod wasm_js; pub use wasm_js::*; } else if #[cfg(target_os = "espidf")] { @@ -127,18 +127,6 @@ cfg_if! { ); } } - } else if #[cfg(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "none")))] { - cfg_if! { - if #[cfg(feature = "js")] { - mod wasm_js; - pub use wasm_js::*; - } else { - compile_error!("the wasm32-unknown-unknown targets are not supported \ - by default, you may need to enable the \"js\" \ - feature flag. For more information see: \ - https://docs.rs/getrandom/#webassembly-support"); - } - } } else if #[cfg(target_os = "hermit")] { mod hermit; pub use hermit::*; @@ -157,6 +145,14 @@ cfg_if! { } else if #[cfg(all(target_arch = "x86_64", target_env = "sgx"))] { mod rdrand; pub use rdrand::*; + } else if #[cfg(all( + target_arch = "wasm32", + any(target_os = "unknown", target_os = "none") + ))] { + compile_error!("the wasm32-unknown-unknown targets are not supported \ + by default, you may need to enable the \"wasm_js\" \ + configuration flag. For more information see: \ + https://docs.rs/getrandom/#webassembly-support"); } else { compile_error!("target is not supported. You may need to define \ a custom backend see: \ diff --git a/src/error.rs b/src/error.rs index d94ca2a4..ccbe7837 100644 --- a/src/error.rs +++ b/src/error.rs @@ -116,7 +116,7 @@ impl Error { Error::IOS_RANDOM_GEN => "SecRandomCopyBytes: iOS Security framework failure", #[cfg(all(windows, target_vendor = "win7"))] Error::WINDOWS_RTL_GEN_RANDOM => "RtlGenRandom: Windows system function failure", - #[cfg(all(feature = "js", getrandom_backend = "wasm_js"))] + #[cfg(all(feature = "wasm_js", getrandom_backend = "wasm_js"))] Error::WEB_CRYPTO => "Web Crypto API is unavailable", #[cfg(target_os = "vxworks")] Error::VXWORKS_RAND_SECURE => "randSecure: VxWorks RNG module is not initialized", diff --git a/tests/mod.rs b/tests/mod.rs index 03247f31..9f1e6338 100644 --- a/tests/mod.rs +++ b/tests/mod.rs @@ -1,7 +1,7 @@ use core::mem::MaybeUninit; use getrandom::{fill, fill_uninit}; -#[cfg(all(feature = "js", target_arch = "wasm32", target_os = "unknown"))] +#[cfg(all(feature = "wasm_js", target_arch = "wasm32", target_os = "unknown"))] use wasm_bindgen_test::wasm_bindgen_test as test; #[test]