Merge pull request #61 from rust-random/work

Revise crates, portability, guide

src/SUMMARY.md

@@ -2,14 +2,15 @@
 
 [Introduction](intro.md)
 
-- [Getting Started](guide-start.md)
+- [Quick start](quick-start.md)
 
-- [Crates and features](crates.md)
-    - [Rand and co](crates-rand.md)
-    - [Random generators](crates-gen.md)
+- [Crates](crates.md)
+    - [Features](crate-features.md)
+    - [Platform support](crate-platforms.md)
+    - [Reproducibility](crate-reprod.md)
 
 - [Guide](guide.md)
-    - [Cargo and features](guide-cargo.md)
+    - [Getting started](guide-start.md)
     - [Random data](guide-data.md)
     - [Types of generators](guide-gen.md)
     - [Our RNGs](guide-rngs.md)
@@ -21,8 +22,6 @@
     - [Sequences](guide-seq.md)
     - [Error handling](guide-err.md)
 
-- [Portability](portability.md)
-
 - [Updating](update.md)
     - [Updating to 0.5](update-0.5.md)
     - [Updating to 0.6](update-0.6.md)

src/crate-features.md

@@ -0,0 +1,38 @@
+# Crate features
+
+For definitive documentation of crate features, check the crate release's `Cargo.toml`:
+
+-   <https://docs.rs/crate/rand/latest/source/Cargo.toml.orig>
+-   <https://docs.rs/crate/rand_core/latest/source/Cargo.toml.orig>
+-   <https://docs.rs/crate/rand_distr/latest/source/Cargo.toml.orig>
+
+## Common features
+
+The following features are common to `rand_core`, `rand`, `rand_distr` and potentially some RNG crates:
+
+-   `std`: opt into functionality dependent on the `std` lib. This is default-enabled except in `rand_core`; for `no_std` usage, use `default-features = false`.
+-   `alloc`: enables functionality requiring an allocator (for usage with `no_std`). This is implied by `std`.
+-   `serde1`: enables serialization via [`serde`], version 1.0.
+
+## Rand features
+
+Additional `rand` features:
+
+-   `small_rng` enables the [`SmallRng`] generator (feature-gated since v0.7).
+-   `simd_support`: Experimental support for generating various SIMD types (requires nightly `rustc`).
+-   `log` enables a few log messages via [`log`].
+
+Note regarding SIMD: the above flag concerns explicit generation of SIMD types
+only and not optimisation. SIMD operations may be used internally regardless of
+this flag; e.g. the ChaCha generator has explicit support for SIMD operations
+internally.
+
+## rand_distr features
+
+The floating point functions from `num_traits` and `libm` are used to support
+`no_std` environments and ensure reproducibility. If the floating point
+functions from `std` are preferred, which may provide better accuracy and
+performance but may produce different random values, the `std_math` feature
+can be enabled. (Note that any other crate depending on `num-traits`'s `std` feature (default-enabled) will have the same effect.)
+
+[`SmallRng`]: https://docs.rs/rand/latest/rand/rngs/struct.SmallRng.html

src/crate-platforms.md

@@ -0,0 +1,22 @@
+# Platform support
+
+Thanks to many community contributions, Rand crates support a wide variety of platforms.
+
+## no_std
+
+With `default-features = false`, both `rand` and `rand_distr` support `no_std` builds. See [Common features](crate-features.html#common-features).
+
+## getrandom
+
+The [`getrandom`] crate provides a low-level API around platform-specific
+random-number sources, and is an important building block of `rand` and
+`rand_core` as well as a number of cryptography libraries.
+It is not intended for usage outside of low-level libraries.
+
+### WebAssembly
+
+The `wasm32-unknown-unknown` target does not make any assumptions about which JavaScript interface is available, thus the `getrandom` crate requires configuration. See [WebAssembly support](https://docs.rs/getrandom/latest/getrandom/#webassembly-support).
+
+Note that the `wasm32-wasi` and `wasm32-unknown-emscripten` targets do not have this limitation.
+
+[`getrandom`]: https://docs.rs/getrandom/

src/portability.md → src/crate-reprod.md

@@ -1,4 +1,4 @@
-# Portability
+# Reproducibility
 
 ## Definitions
 
@@ -61,7 +61,7 @@ upper bound exceeds `u32::MAX`.
 ### Portability of floats
 
 The results of floating point arithmetic depend on rounding modes and
-implementation details. Especially the results of transcendental functions vary
-from platform to platform. Due to this, the distributions in `rand_distr` are
-not always portable for `f32` and `f64`. However, we strive to make them as
-portable as possible.
+implementation details. In particular, the results of transcendental functions vary
+from platform to platform. Due to this, results of distributions in `rand_distr` using `f32` or `f64` may not be portable.
+
+To aleviate (or further complicate) this concern, we prefer to use `libm` over `std` implementations of these transcendental functions. See [rand_distr features](crate-features.html#rand_distr-features).

src/crates.md

@@ -1,61 +1,57 @@
-# Crates and features
-
-The Rand library consists of a family of crates. The [`rand`] crate provides the
-main user-interface; where additional distributions are required, the
-[`rand_distr`] or [`statrs`] crate may be used in addition.
-
-The library contains several building blocks: [`getrandom`] interfaces with the
-platform-dependent random number source, [`rand_core`] defines the API that
-generators must implement, and a number of crates like [`rand_chacha`] and
-[`rand_xoshiro`] provide pseudo-random generators.
-
-```plain
-getrandom ┐
-          └ rand_core ┐
-                      ├ rand_chacha ┐
-                      ├ rand_hc     ┤
-                      ├ rand_pcg    ┤
-                      └─────────────┴ rand ┐
-                                           ├ rand_distr
-                                           └ statrs
-```
-
-## Feature flags
-
-Rand crates allow some configuration via feature flags. Check the READMEs of
-individual crates for details.
-
-No-std support is available across most Rand crates by disabling default
-features: `rand = { version = "0.7", default-features = false }`.
-This is affected by the following flags:
-
--   `std` opts-in to functionality dependent on the `std` lib
--   `alloc` (implied by `std`) enables functionality requiring an allocator
-    (when using this feature in `no_std`, Rand requires Rustc version 1.36 or greater)
-
-Some Rand crates can be built with support for the following third-party crates:
-
--   `log` enables a few log messages via [`log`]
--   `serde1` enables serialization via [`serde`], version 1.0
-
-Note that cryptographic RNGs *do not* support serialisation since this could be
-a security risk. If you need state-restore functionality on a cryptographic RNG,
-the ChaCha generator supports [getting and setting the stream position](https://docs.rs/rand_chacha/latest/rand_chacha/struct.ChaCha20Rng.html#method.get_word_pos),
-which, together with the seed, can be used to reconstruct the generator's state.
-
-## WASM support
-
-Almost all Rand crates support WASM out of the box. However, when using the
-`wasm32-unknown-unknown` target, which doesn't make any assumptions about its
-operating environment by default, the `getrandom` crate may require enabling
-features for seeding entropy via the platform-provided APIs.
-Consequently, if you are using `rand` (or another Rand project crate)
-depending on `getrandom`, you may have to explicitly [enable `getrandom`
-features](https://github.com/rust-random/getrandom#features) for seeding to
-work. Alternatively, in case you are developing for a sandboxed or unknown
-WASM platform that can't depend on environment provided APIs, you might want
-to disable the `rand` crate's `getrandom` feature and seed the generator
-manually.
+# The crate family
+
+<pre><code class="language-plain">                                           ┌ <a href="https://docs.rs/statrs/">statrs</a>
+<a href="https://docs.rs/getrandom/">getrandom</a> ┐                                ├ <a href="https://docs.rs/rand_distr/">rand_distr</a>
+          └ <a href="https://docs.rs/rand_core/">rand_core</a> ┬─────────────┬ <a href="https://docs.rs/rand/">rand</a> ┘
+                      ├ <a href="https://docs.rs/rand_chacha/">rand_chacha</a> ┘
+                      ├ <a href="https://docs.rs/rand_pcg/">rand_pcg</a>
+                      └ [other RNG crates]
+</code></pre>
+
+## Interfaces
+
+[`rand_core`] defines [`RngCore`] and other core traits, as well as several helpers for implementing RNGs.
+
+The [`getrandom`] crate provides a low-level API around platform-specific
+random-number sources.
+
+## Pseudo-random generators
+
+The following crates implement pseudo-random number generators
+(see [Our RNGs](guide-rngs.md)):
+
+-   [`rand_chacha`] provides generators using the ChaCha cipher
+-   [`rand_hc`] implements a generator using the HC-128 cipher
+-   [`rand_isaac`] implements the ISAAC generators
+-   [`rand_pcg`] implements a small selection of PCG generators
+-   [`rand_xoshiro`] implements the SplitMix and Xoshiro generators
+-   [`rand_xorshift`] implements the basic Xorshift generator
+
+Exceptionally, [`SmallRng`] is implemented directly in [`rand`].
+
+## rand (main crate)
+
+The [`rand`] crate is designed for easy usage of common random-number
+functionality. This has several aspects:
+
+-   the [`rngs`] module provides a few convenient generators
+-   the [`distributions`] module concerns sampling of random values
+-   the [`seq`] module concerns sampling from and shuffling sequences
+-   the [`Rng`] trait provides a few convenience methods for generating
+    random values
+-   the [`random`] function provides convenient generation in a single call
+
+## Distributions
+
+The [`rand`] crate only implements sampling from the most common random
+number distributions: uniform and weighted sampling. For everything else,
+
+-   [`rand_distr`] provides fast sampling from a variety of other distributions,
+    including Normal (Gauss), Binomial, Poisson, UnitCircle, and many more
+-   [`statrs`] is a port of the C# Math.NET library, implementing many of the
+    same distributions (plus/minus a few), along with PDF and CDF functions,
+    the *error*, *beta*, *gamma* and *logistic* special functions, plus a few
+    utilities. (For clarity, [`statrs`] is not part of the Rand library.)
 
 
 [`rand_core`]: https://docs.rs/rand_core/
@@ -64,6 +60,20 @@ manually.
 [`statrs`]: https://docs.rs/statrs/
 [`getrandom`]: https://docs.rs/getrandom/
 [`rand_chacha`]: https://docs.rs/rand_chacha/
+[`rand_pcg`]: https://docs.rs/rand_pcg/
 [`rand_xoshiro`]: https://docs.rs/rand_xoshiro/
 [`log`]: https://docs.rs/log/
 [`serde`]: https://serde.rs/
+[`rand_hc`]: https://docs.rs/rand_hc/
+[`rand_isaac`]: https://docs.rs/rand_isaac/
+[`rand_xorshift`]: https://docs.rs/rand_xorshift/
+
+[`RngCore`]: https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html
+
+[`rngs`]: https://docs.rs/rand/latest/rand/rngs/
+[`distributions`]: https://docs.rs/rand/latest/rand/distributions/
+[`seq`]: https://docs.rs/rand/latest/rand/seq/
+[`Rng`]: https://docs.rs/rand/latest/rand/trait.Rng.html
+[`random`]: https://docs.rs/rand/latest/rand/fn.random.html
+
+[`SmallRng`]: https://docs.rs/rand/latest/rand/rngs/struct.SmallRng.html