Merge pull request #1 from dhardy/rand_os

rand_os: doc and cargo improvements

Cargo.toml

@@ -29,7 +29,16 @@ simd_support = ["packed_simd"] # enables SIMD support
 serde1 = ["rand_core/serde1", "rand_isaac/serde1", "rand_xorshift/serde1"] # enables serialization for PRNGs
 
 [workspace]
-members = ["rand_core", "rand_os", "rand_isaac", "rand_chacha", "rand_hc", "rand_pcg", "rand_xorshift"]
+members = [
+    "rand_core",
+    "rand_os",
+    "rand_isaac",
+    "rand_chacha",
+    "rand_hc",
+    "rand_pcg",
+    "rand_xorshift",
+    "rand_xoshiro",
+]
 
 [dependencies]
 rand_core = { path = "rand_core", version = "0.3", default-features = false }
@@ -51,7 +60,7 @@ optional = true
 features = ["into_bits"]
 
 [target.'cfg(unix)'.dependencies]
-libc = "0.2"
+libc = { version = "0.2", default-features = false }
 
 # TODO: check if all features are required
 [target.'cfg(windows)'.dependencies]

rand_os/LICENSE-MIT

@@ -1,5 +1,5 @@
-Copyright (c) 2014-2017 Melissa O'Neill and PCG Project contributors
 Copyright 2018 Developers of the Rand project
+Copyright (c) 2014 The Rust Project Developers
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

rand_os/README.md

@@ -13,6 +13,10 @@ operating system.
 This crate depends on [rand_core](https://crates.io/crates/rand_core) and is
 part of the [Rand project](https://github.com/rust-random/rand).
 
+This crate aims to support all of Rust's `std` platforms with a system-provided
+entropy source. Unlike other Rand crates, this crate does not support `no_std`
+(handling this gracefully is a current discussion topic).
+
 Documentation:
 [master branch](https://rust-random.github.io/rand/rand_os/index.html),
 [by release](https://docs.rs/rand_os)

rand_os/src/lib.rs

@@ -61,7 +61,7 @@
 //! `wasm32-unknown-emscripten` and `wasm32-experimental-emscripten` use
 //! Emscripten's emulation of `/dev/random` on web browsers and Node.js.
 //!
-//! The bare Wasm target `wasm32-unknown-unknown` tries to call the javascript
+//! The bare WASM target `wasm32-unknown-unknown` tries to call the javascript
 //! 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.
@@ -87,12 +87,17 @@
 //! `/dev/random` until we know the OS RNG is initialized (and store this in a
 //! global static).
 //!
-//! # Panics
+//! # Panics and error handling
 //!
-//! `OsRng` is extremely unlikely to fail if `OsRng::new()`, and one read from
-//! it, where succesfull. But in case it does fail, only [`try_fill_bytes`] is
-//! able to report the cause. Depending on the error the other [`RngCore`]
-//! methods will retry several times, and panic in case the error remains.
+//! We cannot guarantee that `OsRng` will fail, but if it does, it will likely
+//! be either when `OsRng::new()` is first called or when data is first read.
+//! If you wish to catch errors early, then test reading of at least one byte
+//! from `OsRng` via [`try_fill_bytes`]. If this succeeds, it is extremely
+//! unlikely that any further errors will occur.
+//! 
+//! Only [`try_fill_bytes`] is able to report the cause of an error; the other
+//! [`RngCore`] methods may (depending on the error kind) retry several times,
+//! but must eventually panic if the error persists.
 //!
 //! [`EntropyRng`]: ../rand/rngs/struct.EntropyRng.html
 //! [`RngCore`]: ../rand_core/trait.RngCore.html

src/rngs/mod.rs

@@ -178,5 +178,5 @@ pub use self::small::SmallRng;
 pub use self::std::StdRng;
 #[cfg(feature="std")] pub use self::thread::ThreadRng;
 
-#[cfg(all(feature="std", feature="rand_os"))]
+#[cfg(feature="std")]
 pub use rand_os::OsRng;

utils/ci/script.sh

@@ -15,6 +15,7 @@ main() {
     cross test --target $TARGET --manifest-path rand_xoshiro/Cargo.toml
     cross test --target $TARGET --manifest-path rand_chacha/Cargo.toml
     cross test --target $TARGET --manifest-path rand_hc/Cargo.toml
+    cross test --target $TARGET --manifest-path rand_os/Cargo.toml
 }
 
 # we don't run the "test phase" when doing deploys