[Request] Update documentation to mention potential `no_std` problem.

[0ndorio]

Disclaimer: This is actually not an issue with hashbrown but with cargo.

---

Topic: no_std support

While hashbrown itself is able to compile successfully for no_std targets, and even uses the CI pipeline to verify its compatibility to the thumbv6m-none-eabi target, it might still trigger issues if used with other dependencies when the default ahash feature is enabled.

Issue

The dependency tree of ahash injects the getrandom crate if the default feature set is enabled. This crate is heavily platform dependent and does not support targets like the thumbv6 or thumbv7 families.

How does this happen?

The underlying issue is an a long standing and well known cargo bug (rust-lang/cargo#5760) which automatically calculates a required feature set for each (sub-)dependency inside the dependency tree regardless of the dependency origin.

If ahash - with default feature set - is used, it will include the const-random crate and therefore the proc macro crate const-random-macro into the dependency tree. This will request the getrandom feature for the crates rand v^0.7 and indirectly also rand_core v^0.5.1.

As dependencies of proc macros are compiled for the host and not the target architecture this works fine as long as the host architecture is contained in the following list and the no_std build should be successful (as you can see inside the CI).

But it is going to fail as soon as one of the following two conditions are true:

• The host architecture is not supported.

• The target architecture is not supported and the dependency tree contains at least one non proc macro dependency, which requires either rand v^0.7 or rand_core v^0.5.1, because than the underlying cargo issue kicks in. Cargo is going to inject the getrandom feature requirement for these crates, originating from the dependency list of const-random-macro, into the other dependency so that cargo is trying to compile getrandom not only for the host architecture but also for the target architecture.

Request

As long as rust-lang/cargo#5760 is still a thing it would be great if at least the hashbrown documentation could get a warning paragraph explaining this topic including how to work around this issue.

Potential workarounds I can see:

• hashbrown could introduce a way to disable the compile-time-rng feature of ahash if default features are disabled.

• The relying crate could disable the ahash feature of hashbrown and reintroduce another hasher or ahash without compile-time-rng feature.

Both might result in ahash losing the compile time random seed for the hash values.

[Amanieu]

I'm happy to allow disabling compile-time-rng via a feature. Would you be willing to submit a PR?