diff --git a/Cargo.toml b/Cargo.toml index 41fc368..a7297e9 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,11 +19,24 @@ required-features = ["alloc"] [features] default = ["alloc"] # default features are automatically enables (if not opt-out) -alloc = ["hashbrown"] # requires global allocator, enables various functions such as parse_alias +alloc = [ # requires global allocator, enables various functions such as parse_alias + "hashbrown", + "lazy_static" +] doc_cfg = [] # requires nightly compiler, only intended for docs.rs builds (enables usage of doc_cfg) [dependencies] -lazy_static = "1.4.0" + +[dependencies.lazy_static] +version = "1.4.0" +optional = true +# The following feature on `lazy_static` would remove the transitive dependency of lazy_static on +# std, which is necessary if targetting a platform without it. However, since the current version +# of Cargo (1.51.0) unifies features acros crates, requiring that feature here, would make +# lazy_static globally use spinloks instead of mutices. So, it seems more reasonable that a final +# user (binary crate) adds this feature if they want `alloc` but not `std`. +# Also see: https://github.com/rust-lang-nursery/lazy-static.rs/issues/150 +#features = ["spin_no_std"] # Would remove std from lazy_static, but it has side-effects [dependencies.hashbrown] version = "0.11" diff --git a/README.md b/README.md index 402aeb5..bf90383 100644 --- a/README.md +++ b/README.md @@ -124,14 +124,32 @@ platforms. However, some functions such as [`parse_alias`](https://docs.rs/emoji ad-hoc flag functions need the `alloc` crate (normally part of `std`), thus it is enabled by default. -- `default`: (implies `alloc`) automatically enabled if not opt-out: +- `default`: (implies `alloc`) \ + Automatically enabled if not opt-out: ```toml [dependencies.emojic] version = "0.3" default-features = false ``` -- `alloc`: requires a global allocator, enables various functions such as `parse_alias` as well - as the ad-hoc flag functions (the flag constants are unaffected) +- `alloc`: (implies `hashbrown` and `lazy_static`) \ + Requires a global allocator, + enables various functions such as `parse_alias` as well + as the ad-hoc flag functions (the flag constants are unaffected). + + Notice, that `lazy_static`, by default, pulls-in `std` to use mutices for waiting. + This is good if you do have `std` available, and bad if not. However, the alternative is + to instruct `lazy_static` to use spinlocks instead. Yet, since crate-features are unified by + Cargo, it would be bad for all user that have `std`, to requiring it by default. + Instead, if you want to use this `alloc` feature, but you don't have `std` + (e.g. in your binary crate), you can simply add `lazy_static` yourself, and make it to use + spinlocks, which will apply globally. E.g. add to your `Cargo.toml`: + ```toml + [dependencies.lazy_static] + version = "1.4" + features = ["spin_no_std"] + ``` + Also see: + diff --git a/src/lib.rs b/src/lib.rs index 804d83b..526044d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -142,14 +142,32 @@ //! ad-hoc flag functions need the `alloc` crate (normally part of `std`), //! thus it is enabled by default. //! -//! - `default`: (implies `alloc`) automatically enabled if not opt-out: +//! - `default`: (implies `alloc`) \ +//! Automatically enabled if not opt-out: //! ```toml //! [dependencies.emojic] //! version = "0.3" //! default-features = false //! ``` -//! - `alloc`: requires a global allocator, enables various functions such as `parse_alias` as well -//! as the ad-hoc flag functions (the flag constants are unaffected) +//! - `alloc`: (implies `hashbrown` and `lazy_static`) \ +//! Requires a global allocator, +//! enables various functions such as `parse_alias` as well +//! as the ad-hoc flag functions (the flag constants are unaffected). +//! +//! Notice, that `lazy_static`, by default, pulls-in `std` to use mutices for waiting. +//! This is good if you do have `std` available, and bad if not. However, the alternative is +//! to instruct `lazy_static` to use spinlocks instead. Yet, since crate-features are unified by +//! Cargo, it would be bad for all user that have `std`, to requiring it by default. +//! Instead, if you want to use this `alloc` feature, but you don't have `std` +//! (e.g. in your binary crate), you can simply add `lazy_static` yourself, and make it to use +//! spinlocks, which will apply globally. E.g. add to your `Cargo.toml`: +//! ```toml +//! [dependencies.lazy_static] +//! version = "1.4" +//! features = ["spin_no_std"] +//! ``` +//! Also see: +//! //! //!