Feature-gate the SmallRng generator

Author: dhardy

Cargo.toml

@@ -35,6 +35,7 @@ getrandom = ["getrandom_package", "rand_core/getrandom"]
 
 # Configuration:
 simd_support = ["packed_simd"] # enables SIMD support
+small_rng = ["rand_pcg"]    # enables SmallRng
 
 [workspace]
 members = [
@@ -53,8 +54,8 @@ members = [
 
 [dependencies]
 rand_core = { path = "rand_core", version = "0.4" }
-rand_pcg = { path = "rand_pcg", version = "0.1" }
 rand_hc = { path = "rand_hc", version = "0.1" }
+rand_pcg = { path = "rand_pcg", version = "0.1", optional = true }
 # Do not depend on 'getrandom_package' directly; use the 'getrandom' feature!
 getrandom_package = { version = "0.1.1", package = "getrandom", optional = true }
 log = { version = "0.4", optional = true }

README.md

@@ -102,6 +102,7 @@ Optionally, the following dependencies can be enabled:
 
 Additionally, these features configure Rand:
 
+-   `small_rng` enables inclusion of the `SmallRng` PRNG
 -   `nightly` enables all experimental features
 -   `simd_support` (experimental) enables sampling of SIMD values
     (uniformly random SIMD integers and floats)

src/distributions/mod.rs

@@ -324,7 +324,7 @@ impl<D, R, T> iter::TrustedLen for DistIter<D, R, T>
 /// use rand::prelude::*;
 /// use rand::distributions::Standard;
 ///
-/// let val: f32 = SmallRng::from_entropy().sample(Standard);
+/// let val: f32 = StdRng::from_entropy().sample(Standard);
 /// println!("f32 from [0, 1): {}", val);
 /// ```
 ///

src/lib.rs

@@ -63,7 +63,7 @@ extern crate getrandom_package as getrandom;
 
 extern crate rand_core;
 extern crate rand_hc;
-extern crate rand_pcg;
+#[cfg(feature="small_rng")] extern crate rand_pcg;
 
 #[cfg(feature = "log")] #[macro_use] extern crate log;
 #[allow(unused)]

src/prelude.rs

@@ -14,13 +14,14 @@
 //!
 //! ```
 //! use rand::prelude::*;
-//! # let _ = StdRng::from_entropy();
-//! # let mut r = SmallRng::from_rng(thread_rng()).unwrap();
+//! # let mut r = StdRng::from_rng(thread_rng()).unwrap();
 //! # let _: f32 = r.gen();
 //! ```
 
 #[doc(no_inline)] pub use distributions::Distribution;
-#[doc(no_inline)] pub use rngs::{SmallRng, StdRng};
+#[doc(no_inline)] pub use rngs::StdRng;
+#[cfg(feature="small_rng")]
+#[doc(no_inline)] pub use rngs::SmallRng;
 #[doc(no_inline)] #[cfg(feature="std")] pub use rngs::ThreadRng;
 #[doc(no_inline)] pub use {Rng, RngCore, CryptoRng, SeedableRng};
 #[doc(no_inline)] #[cfg(feature="std")] pub use {random, thread_rng};

src/rngs/mod.rs

@@ -104,13 +104,15 @@ pub mod adapter;
 #[cfg(feature="std")] mod entropy;
 pub mod mock;   // Public so we don't export `StepRng` directly, making it a bit
                 // more clear it is intended for testing.
+#[cfg(feature="small_rng")]
 mod small;
 mod std;
 #[cfg(feature="std")] pub(crate) mod thread;
 
 #[allow(deprecated)]
 #[cfg(feature="std")] pub use self::entropy::EntropyRng;
 
+#[cfg(feature="small_rng")]
 pub use self::small::SmallRng;
 pub use self::std::StdRng;
 #[cfg(feature="std")] pub use self::thread::ThreadRng;

src/rngs/small.rs

@@ -15,22 +15,28 @@ type Rng = ::rand_pcg::Pcg64Mcg;
 #[cfg(not(all(all(rustc_1_26, not(target_os = "emscripten")), target_pointer_width = "64")))]
 type Rng = ::rand_pcg::Pcg32;
 
-/// An RNG recommended when small state, cheap initialization and good
-/// performance are required. The PRNG algorithm in `SmallRng` is chosen to be
-/// efficient on the current platform, **without consideration for cryptography
-/// or security**. The size of its state is much smaller than for [`StdRng`].
+/// A small-state, fast non-crypto PRNG
 ///
-/// Reproducibility of output from this generator is however not required, thus
-/// future library versions may use a different internal generator with
-/// different output. Further, this generator may not be portable and can
-/// produce different output depending on the architecture. If you require
-/// reproducible output, use a named RNG.
-/// Refer to [The Book](https://rust-random.github.io/book/guide-rngs.html).
-/// 
+/// `SmallRng` may be a good choice when a PRNG with small state, cheap
+/// initialization, good statistical quality and good performance are required.
+/// It is **not** a good choice when security against prediction or
+/// reproducibility are important.
 ///
-/// The current algorithm is [`Pcg64Mcg`][rand_pcg::Pcg64Mcg] on 64-bit platforms with Rust version
-/// 1.26 and later, or [`Pcg32`][rand_pcg::Pcg32] otherwise. Both are found in
-/// the [rand_pcg] crate.
+/// This PRNG is **feature-gated**: to use, you must enable the crate feature
+/// `small_rng`.
+///
+/// The algorithm is deterministic but should not be considered reproducible
+/// due to dependence on platform and possible replacement in future
+/// library versions. For a reproducible generator, use a named PRNG from an
+/// external crate, e.g. [rand_pcg] or [rand_chacha].
+/// Refer also to [The Book](https://rust-random.github.io/book/guide-rngs.html).
+///
+/// The PRNG algorithm in `SmallRng` is chosen to be
+/// efficient on the current platform, without consideration for cryptography
+/// or security. The size of its state is much smaller than [`StdRng`].
+/// The current algorithm is [`Pcg64Mcg`][rand_pcg::Pcg64Mcg] on 64-bit
+/// platforms and [`Pcg32`][rand_pcg::Pcg32] on 32-bit platforms. Both are
+/// implemented by the [rand_pcg] crate.
 ///
 /// # Examples
 ///