Add more examples with explanations to Ch 3.4. Features - help offered #8431
Labels
A-documenting-cargo-itself
Area: Cargo's documentation
A-features
Area: features — conditional compilation
Describe the problem you are trying to solve
Ch. 3.4 Features in Cargo Book is technically correct and makes perfect sense for someone who already understands how it works. It is rather incomplete for a newcomer. Adding a couple more examples with explanations how they work would help to grasp the topic on the first read.
Describe the solution you'd like
and provide several possible configurations for it with explanations what features will be enabled when. E.g.
dynomite = {version = "0.8.2", default-features = false, features = ["rustls", "derive"]}
dynomite = "0.8.2"
dynomite = {version = "0.8.2", features = ["rustls", "derive"]}
- fails to build, explain whyIf this is something that is already explained elsewhere in the book there should be a link to it from Ch.3.4.
It would also help to explain how to discover features of particular crate if they are not documented. It is very straight-forward once you understand the topic, but for someone still struggling with it this advice on StackOverflow was extremely helpful. It could be distilled to one sentence like ..
Notes
I am probably thicker than the average Rust programmer, so it took me a while to wrap my head around the exact syntax of
[features]
section and how it relates to[dependencies]
,rustc --features
and what is enabled when. The penny dropped after I cross-referenced these sources:and re-read https://doc.rust-lang.org/cargo/reference/features.html.
I think the learning curve can be eased if there was a more detailed example right in the book.
I am happy to attempt a PR if there is consensus on this issue.
The text was updated successfully, but these errors were encountered: