Add dummy feature (#71)

Author: newpavlov

Cargo.toml

@@ -37,5 +37,7 @@ stdweb = { version = "0.4.18", optional = true }
 
 [features]
 std = []
+# enables dummy implementation for unsupported targets
+dummy = []
 # Unstable feature to support being a libstd dependancy
 rustc-dep-of-std = ["compiler_builtins", "core"]

README.md

@@ -18,7 +18,6 @@ library like [`rand`].
 
 [`rand`]: https://crates.io/crates/rand
 
-
 ## Usage
 
 Add this to your `Cargo.toml`:
@@ -48,17 +47,27 @@ will require linking against system libraries (i.e. `libc` for Unix,
 The `log` library is supported as an optional dependency. If enabled, error
 reporting will be improved on some platforms.
 
-For WebAssembly (`wasm32`), WASI and Emscripten targets are supported directly; otherwise
-one of the following features must be enabled:
+For the `wasm32-unknown-unknown` target, one of the following features should be
+enabled:
 
 -   [`wasm-bindgen`](https://crates.io/crates/wasm_bindgen)
 -   [`stdweb`](https://crates.io/crates/stdweb)
 
+By default, compiling `getrandom` for an unsupported target will result in
+a compilation error. If you want to build an application which uses `getrandom`
+for such target, you can either:
+- Use [`[replace]`][replace] or [`[patch]`][patch] section in your `Cargo.toml`
+to switch to a custom implementation with a support of your target.
+- Enable the `dummy` feature to have getrandom use an implementation that always
+fails at run-time on unsupported targets.
+
+[replace]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-replace-section
+[patch]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-patch-section
+
 ## Minimum Supported Rust Version
 
 This crate requires Rust 1.32.0 or later.
 
-
 # License
 
 The `getrandom` library is distributed under either of
@@ -67,4 +76,3 @@ The `getrandom` library is distributed under either of
  * [MIT license](LICENSE-MIT)
 
 at your option.
-

src/lib.rs

@@ -36,7 +36,19 @@
 //! systems are using the recommended interface and respect maximum buffer
 //! sizes.
 //!
-//! ## Support for WebAssembly and ams.js
+//! ## Unsupported targets
+//! By default, compiling `getrandom` for an unsupported target will result in
+//! a compilation error. If you want to build an application which uses `getrandom`
+//! for such target, you can either:
+//! - Use [`[replace]`][replace] or [`[patch]`][patch] section in your `Cargo.toml`
+//! to switch to a custom implementation with a support of your target.
+//! - Enable the `dummy` feature to have getrandom use an implementation that always
+//! fails at run-time on unsupported targets.
+//!
+//! [replace]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-replace-section
+//! [patch]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-patch-section
+//!
+//! ## Support for WebAssembly and asm.js
 //!
 //! The three Emscripten targets `asmjs-unknown-emscripten`,
 //! `wasm32-unknown-emscripten` and `wasm32-experimental-emscripten` use
@@ -46,7 +58,9 @@
 //! methods directly, using either `stdweb` or `wasm-bindgen` depending on what
 //! features are activated for this crate. Note that if both features are
 //! enabled `wasm-bindgen` will be used. If neither feature is enabled,
-//! `getrandom` will always fail.
+//! compiling `getrandom` will result in a compilation error. It can be avoided
+//! by enabling the `dummy` feature, which will make `getrandom` to use an
+//! always failing implementation.
 //!
 //! The WASI target `wasm32-wasi` uses the `__wasi_random_get` function defined
 //! by the WASI standard.
@@ -221,18 +235,20 @@ cfg_if! {
                   target_env = "sgx",
               )))] {
         #[path = "rdrand.rs"] mod imp;
-    } else if #[cfg(target_arch = "wasm32")] {
-        cfg_if! {
-            if #[cfg(feature = "wasm-bindgen")] {
-                #[path = "wasm32_bindgen.rs"] mod imp;
-            } else if #[cfg(feature = "stdweb")] {
-                #[path = "wasm32_stdweb.rs"] mod imp;
-            } else {
-                #[path = "dummy.rs"] mod imp;
-            }
-        }
-    } else {
+    // the following two branches are intended only for `wasm32-unknown-unknown`
+    // target and may not work or work inefficiently on targets which may be
+    // added in future
+    } else if #[cfg(all(target_arch = "wasm32", feature = "wasm-bindgen"))] {
+        #[path = "wasm32_bindgen.rs"] mod imp;
+    } else if #[cfg(all(target_arch = "wasm32", feature = "stdweb"))] {
+        #[path = "wasm32_stdweb.rs"] mod imp;
+    } else if #[cfg(feature = "dummy")] {
         #[path = "dummy.rs"] mod imp;
+    } else {
+        compile_error!("\
+            target is not supported, for more information see: \
+            https://docs.rs/getrandom/#unsupported-targets\
+        ");
     }
 }