Clarify that `libm` is needed for `no_std`

ChocolateLoverRaj commented 3 weeks ago

There are tons of errors when trying to build palette with --no-default-features.

How To Reproduce

Can reproduce on cargo 1.82.0-nightly (2f738d617 2024-08-13) and cargo 1.80.1 (376290515 2024-07-16)
Clone this repo
cd palette
Run cargo b --no-default-features

Expected Outcome

Builds without errors

Actual Outcome

32 errors. Here is one of them:

error[E0277]: the trait bound `f32: Round` is not satisfied
   --> palette/src/angle.rs:127:40
    |
127 |                     self - Round::ceil(((self + 180.0) / 360.0) - 1.0) * 360.0
    |                            ----------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `Round` is not implemented for `f32`
    |                            |
    |                            required by a bound introduced by this call
...
179 | impl_angle_float!(f32, f64);
    | --------------------------- in this macro invocation
    |
help: this trait has no implementations, consider adding one
   --> palette/src/num.rs:234:1
    |
234 | pub trait Round {
    | ^^^^^^^^^^^^^^^
    = note: this error originates in the macro `impl_angle_float` (in Nightly builds, run with -Z macro-backtrace for more info)

Additional Details

I am trying to use palette on the thumbv6m-none-eabi target. I am trying to use palette to control the onboard RGB LED on a RP2040 Zero.

Cargo.toml entry: no changes
Rust version(s): cargo 1.82.0-nightly (2f738d617 2024-08-13) and cargo 1.80.1 (376290515 2024-07-16)
Target platform:  x86_64-unknown-linux-gnu and thumbv6m-none-eabi

Ogeon commented 3 weeks ago

Hi! Many floating point functions need a library implementation and that's usually provided by std. When disabling std, you can enable the "libm" feature, as shown in the readme example:

[dependencies.palette]
version = "0.7.6"
default-features = false
features = ["libm"] # Uses libm instead of std for floating point math

The corresponding argument to cargo build would be --features libm.

ChocolateLoverRaj commented 3 weeks ago

Thanks, that fixed it. I think the fact that libm is required for no_std should be added to the docs. Or maybe there should be a feature called no_std which activates the libm feature.

Ogeon commented 3 weeks ago

I suppose it could be added to the getting started part of the crate root docs too. :thinking: Was that where you were looking?

ChocolateLoverRaj commented 3 weeks ago

Was that where you were looking?

Yes. I also looked in the list of features to see if there was a no_std feature.

Ogeon commented 3 weeks ago

I see, thanks. A no_std feature tends to be an anti-pattern, as it's a "negative feature". I'm happy to clarify things, though. The section at https://crates.io/crates/palette could perhaps highlight it more, for example. It's hard to see these things for me, who's familiar with it already.

spookyvision commented 2 weeks ago

I'd love a "crate features" section in the docs! (feature flags are sadly imho a rather weak spot in Rust/cargo. You can't express mandatory sets of features/combinations apart from rolling your own with compile_error!, and rustdoc doesn't parse feature comments in Cargo.toml…)

Ogeon commented 2 weeks ago

Absolutely, that's also a possible improvement.

Ogeon / palette