Skip to content
Snippets Groups Projects
Commit b4160604 authored by Joe Richey's avatar Joe Richey Committed by Joseph Richey
Browse files

docs: Clarify when/where to use custom implementations


Signed-off-by: default avatarJoe Richey <joerichey@google.com>
parent e8ff2222
No related branches found
No related tags found
No related merge requests found
......@@ -25,12 +25,12 @@ use core::num::NonZeroU32;
/// [dependencies]
/// getrandom = { version = "0.2", features = ["custom"] }
/// ```
///
///
/// Next, in `dummy-getrandom/src/lib.rs`, we define our custom implementation and register it:
/// ```rust
/// use core::num::NonZeroU32;
/// use getrandom::{Error, register_custom_getrandom};
///
///
/// const MY_CUSTOM_ERROR_CODE: u32 = Error::CUSTOM_START + 42;
/// fn always_fail(buf: &mut [u8]) -> Result<(), Error> {
/// let code = NonZeroU32::new(MY_CUSTOM_ERROR_CODE).unwrap();
......@@ -43,10 +43,9 @@ use core::num::NonZeroU32;
/// [`getrandom::getrandom`](crate::getrandom).
///
/// Now any user of `getrandom` (direct or indirect) on this target will use the
/// above custom implementation. Note that if you are using a helper-crate, some
/// crate in the build needs to depend on `dummy-getrandom` via a
/// `use dummy_getrandom;` statement. Failure to do this will result
/// in linker errors.
/// above custom implementation. See the
/// [usage documentation](index.html#use-a-custom-implementation) for information about
/// _using_ such a custom implementation.
#[macro_export]
macro_rules! register_custom_getrandom {
($path:path) => {
......
......@@ -82,6 +82,21 @@
//! are building for an unsupported target, `getrandom` will use this external
//! implementation instead of failing to compile.
//!
//! Using such an external implementation requires depending on it in your
//! `Cargo.toml` _and_ using it in your binary crate with:
//! ```ignore
//! use some_custom_getrandom_crate;
//! ```
//! (failure to do this will cause linker errors).
//!
//! Other than [dev-dependencies](https://doc.rust-lang.org/stable/rust-by-example/testing/dev_dependencies.html),
//! library crates should **not** depend on external implementation crates.
//! Only binary crates should depend/use such crates. This is similar to
//! [`#[panic_handler]`](https://doc.rust-lang.org/nomicon/panic-handler.html) or
//! [`#[global_allocator]`](https://doc.rust-lang.org/edition-guide/rust-2018/platform-and-target-support/global-allocators.html),
//! where helper crates define handlers/allocators but only the binary crate
//! actually _uses_ the functionality.
//!
//! See [`register_custom_getrandom!`] for information about writing your own
//! custom `getrandom` implementation for an unsupported target.
//!
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment