Respond to comments

Author: josephlr

.travis.yml

@@ -21,7 +21,6 @@ matrix:
         - rustup target add aarch64-apple-ios
       script:
         - cargo test
-        - cargo test --examples
         - cargo build --target aarch64-apple-ios
 
     - name: "Linux, beta"
@@ -81,41 +80,32 @@ matrix:
         - GECKODRIVER=$HOME/geckodriver cargo test --target wasm32-unknown-unknown --features=test-in-browser
         - CHROMEDRIVER=$HOME/chromedriver cargo test --target wasm32-unknown-unknown --features=test-in-browser
 
-    - name: "Linux, nightly, docs"
+    - &nightly_and_docs
+      name: "Linux, nightly, docs"
       rust: nightly
       os: linux
       install:
         - cargo --list | egrep "^\s*deadlinks$" -q || cargo install cargo-deadlinks
         - cargo deadlinks -V
       script:
+        # Check that our tests pass in the default configuration
         - cargo test
         - cargo test --benches
-        - cargo test --examples
+        # Check that setting various features does not break the build
+        - cargo build --features=std
+        - cargo build --features=log
+        - cargo build --features=custom
         # remove cached documentation, otherwise files from previous PRs can get included
         - rm -rf target/doc
-        - cargo doc --no-deps --features=std,log
+        - cargo doc --no-deps --features=std,log,custom
         - cargo deadlinks --dir target/doc
         # also test minimum dependency versions are usable
         - cargo generate-lockfile -Z minimal-versions
-        - cargo test
+        - cargo test --features=std,log,custom
 
-    - name: "OSX, nightly, docs"
-      rust: nightly
+    - <<: *nightly_and_docs
+      name: "OSX, nightly, docs"
       os: osx
-      install:
-        - cargo --list | egrep "^\s*deadlinks$" -q || cargo install cargo-deadlinks
-        - cargo deadlinks -V
-      script:
-        - cargo test
-        - cargo test --benches
-        - cargo test --examples
-        # remove cached documentation, otherwise files from previous PRs can get included
-        - rm -rf target/doc
-        - cargo doc --no-deps --features=std,log
-        - cargo deadlinks --dir target/doc
-        # also test minimum dependency versions are usable
-        - cargo generate-lockfile -Z minimal-versions
-        - cargo test
 
     - name: "cross-platform build only"
       rust: nightly
@@ -201,7 +191,6 @@ before_script:
 
 script:
   - cargo test
-  - cargo test --examples
 
 after_script: set +e
 

custom/stdweb/Cargo.toml

@@ -1,16 +1,16 @@
 [package]
-name = "getrandom-stdweb"
+name = "stdweb-getrandom"
 version = "0.2.0"
 edition = "2018"
 authors = ["The Rand Project Developers"]
 license = "MIT OR Apache-2.0"
 description = "Custom shim for using getrandom with stdweb"
-documentation = "https://docs.rs/getrandom-stdweb"
+documentation = "https://docs.rs/stdweb-getrandom"
 repository = "https://github.com/rust-random/getrandom"
 categories = ["wasm"]
 
 [dependencies]
-getrandom = { path = "../..", features = ["custom"] }
+getrandom = { path = "../..", version = "0.2", features = ["custom"] }
 stdweb = "0.4.18"
 log = "0.4"
 

custom/wasm-bindgen/Cargo.toml

@@ -1,16 +1,16 @@
 [package]
-name = "getrandom-wasm-bindgen"
+name = "wasm-bindgen-getrandom"
 version = "0.2.0"
 edition = "2018"
 authors = ["The Rand Project Developers"]
 license = "MIT OR Apache-2.0"
 description = "Custom shim for using getrandom with wasm-bindgen"
-documentation = "https://docs.rs/getrandom-bindgen"
+documentation = "https://docs.rs/wasm-bindgen-getrandom"
 repository = "https://github.com/rust-random/getrandom"
 categories = ["wasm"]
 
 [dependencies]
-getrandom = { path = "../..", features = ["custom"] }
+getrandom = { path = "../..", version = "0.2", features = ["custom"] }
 wasm-bindgen = "0.2.29"
 
 [dev-dependencies]

src/custom.rs

@@ -10,6 +10,28 @@
 use crate::Error;
 use core::num::NonZeroU32;
 
+/// Register a function to be invoked by `getrandom` on custom targets. This
+/// function will only be invoked on targets not supported by `getrandom`. This
+/// prevents crate dependencies from either inadvertently or maliciously
+/// overriding the secure RNG implementations in `getrandom`.
+///
+/// *This API requires the following crate features to be activated: `custom`*
+#[macro_export]
+macro_rules! register_custom_getrandom {
+    ($path:path) => {
+        // We use an extern "C" function to get the guarantees of a stable ABI.
+        #[no_mangle]
+        extern "C" fn __getrandom_custom(dest: *mut u8, len: usize) -> u32 {
+            let slice = unsafe { ::std::slice::from_raw_parts_mut(dest, len) };
+            match $path(slice) {
+                Ok(()) => 0,
+                Err(e) => e.code().get(),
+            }
+        }
+    };
+}
+
+#[allow(dead_code)]
 pub fn getrandom_inner(dest: &mut [u8]) -> Result<(), Error> {
     extern "C" {
         fn __getrandom_custom(dest: *mut u8, len: usize) -> u32;

src/error.rs

@@ -31,7 +31,7 @@ impl Error {
     pub const UNSUPPORTED: Error = internal_error!(0);
     /// The platform-specific `errno` returned a non-positive value.
     pub const ERRNO_NOT_POSITIVE: Error = internal_error!(1);
-    /// Invalid conversion from a non-standard [`std::io::Error`]
+    /// Invalid conversion from a non-standard [`std::io::Error`](https://doc.rust-lang.org/std/io/struct.Error.html)
     pub const UNKNOWN_IO_ERROR: Error = internal_error!(2);
     /// Call to [`SecRandomCopyBytes`](https://developer.apple.com/documentation/security/1399291-secrandomcopybytes) failed.
     pub const SEC_RANDOM_FAILED: Error = internal_error!(3);
@@ -52,13 +52,6 @@ impl Error {
     /// On VxWorks, random number generator is not yet initialized.
     pub const RAND_SECURE_FATAL: Error = internal_error!(11);
 
-    #[deprecated(since = "0.1.7")]
-    /// Unknown error.
-    pub const UNKNOWN: Error = Error::UNSUPPORTED;
-    #[deprecated(since = "0.1.7")]
-    /// System entropy source is unavailable.
-    pub const UNAVAILABLE: Error = Error::UNSUPPORTED;
-
     /// Codes below this point represent OS Errors (i.e. positive i32 values).
     /// Codes at or above this point, but below [`Error::CUSTOM_START`] are
     /// reserved for use by the `rand` and `getrandom` crates.
@@ -70,9 +63,11 @@ impl Error {
 
     /// Extract the raw OS error code (if this error came from the OS)
     ///
-    /// This method is identical to `std::io::Error::raw_os_error()`, except
+    /// This method is identical to [`std::io::Error::raw_os_error()`][1], except
     /// that it works in `no_std` contexts. If this method returns `None`, the
     /// error value can still be formatted via the `Display` implementation.
+    ///
+    /// [1]: https://doc.rust-lang.org/std/io/struct.Error.html#method.raw_os_error
     #[inline]
     pub fn raw_os_error(self) -> Option<i32> {
         if self.0.get() < Self::INTERNAL_START {
@@ -171,7 +166,9 @@ fn internal_desc(error: Error) -> Option<&'static str> {
         Error::BINDGEN_GRV_UNDEF => Some("wasm-bindgen: crypto.getRandomValues is undefined"),
         Error::STDWEB_NO_RNG => Some("stdweb: no randomness source available"),
         Error::STDWEB_RNG_FAILED => Some("stdweb: failed to get randomness"),
-        Error::RAND_SECURE_FATAL => Some("randSecure: random number generator module is not initialized"),
+        Error::RAND_SECURE_FATAL => {
+            Some("randSecure: random number generator module is not initialized")
+        }
         _ => None,
     }
 }

src/lib.rs

@@ -155,7 +155,10 @@ cfg_if! {
 
 mod error;
 mod util;
-
+// To prevent a breaking change when targets are added, we always export the
+// register_custom_getrandom macro, so old Custom RNG crates continue to build.
+#[cfg(feature = "custom")]
+mod custom;
 #[cfg(feature = "std")]
 mod error_impls;
 
@@ -210,7 +213,7 @@ cfg_if! {
               )))] {
         #[path = "rdrand.rs"] mod imp;
     } else if #[cfg(feature = "custom")] {
-        #[path = "custom.rs"] mod imp;
+        use custom as imp;
     } else {
         compile_error!("\
             target is not supported, for more information see: \
@@ -219,28 +222,6 @@ cfg_if! {
     }
 }
 
-/// Register a function to be invoked by `getrandom` on custom targets. This
-/// function will only be invoked on targets not supported by `getrandom`. This
-/// prevents crate dependencies from either inadvertently or maliciously
-/// overriding the secure RNG implementations in `getrandom`.
-///
-/// *This API requires the following crate features to be activated: `custom`*
-#[macro_export]
-#[cfg(feature = "custom")]
-macro_rules! register_custom_getrandom {
-    ($path:path) => {
-        // We use an extern "C" function to get the guarantees of a stable ABI.
-        #[no_mangle]
-        extern "C" fn __getrandom_custom(dest: *mut u8, len: usize) -> u32 {
-            let slice = unsafe { ::std::slice::from_raw_parts_mut(dest, len) };
-            match $path(slice) {
-                Ok(()) => 0,
-                Err(e) => e.code().get(),
-            }
-        }
-    };
-}
-
 /// Fill `dest` with random bytes from the system's preferred random number
 /// source.
 ///