Feature flags in docs

[bugadani]

The docs lists a bunch of feature flags that have been removed or merged with others. I think it may not have been updated when those changes happened, although I can't be sure because the list seems long untouched.

What's especially interesting to me is that the docs mention feature flags that have the same name as dependencies, which should have never worked as far as I can understand. Quoting the cargo book:

Note: A feature in the [feature] table cannot use the same name as a dependency. Experimental support for enabling this and other extensions is available on the nightly channel via namespaced features.

[bugadani]

This came up because I wanted to add heapless::Vec as a OctetsBuilder, but wasn't sure if I could add the dependency to the interop flag or I should add a different feature flag - I couldn't find documentation about the interop flag.

[partim]

Looking at both src/lib.rs and Cargo.toml, I think we only lack documentation for the resolv-sync, random, interop, and ci-test features. We’ll fix that before a release.

The interop feature is intended to activate interoperability tests that rely on other software to be installed in the system (currently NSD and dig) and will fail if it isn’t. That’s why we moved it to a separate feature and (now) have a ci-test feature that enables everything except interop and is used instead of --all-features in the CI workflow. The tests in question live in src/test.

Using the names of optional dependencies as feature names is completely fine – this is how they are enabled after all. So, in our case, adding the bytes feature will both make the bytes crate a dependency and impl a bunch of things for bytes::Bytes. Crucially, however, the impls for Bytes won’t appear just because you have bytes somewhere in your dependency tree. You have to also state features = [ "bytes" ] for domain in your Cargo.toml somewhere. That’s why we list bytes as a feature in the documentation.

What the Cargo book refers to is having the name of an optional crate as the name of an explicit feature defined in the feature section. That really doesn’t work (and is a bit of a shame, since you cannot automatically pull in additional optional crates if one optional crate is enabled).

So, if you want to optionally impl the octets traits for things from heapless – which we are happy to include –, simply adding heaplessas an optional dependency and then use #[cfg(feature = "heapless")] for the impl blocks is the way to go.

[bugadani]

That’s why we list bytes as a feature in the documentation.

Makes sense, I didn't know about this and was trying to add a heapless = ["heapless"] feature.

[bugadani]

Oh, the other issue reminds me: heapless requires 1.51. Is the MSRV bump acceptable?

[partim]

It is. I made #120 for it.