Description
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
- add a more detailed example such as ...
[dependencies]
...
log = "0.4"
rusoto_core_default = { package = "rusoto_core", version = "0.44", optional = true }
rusoto_core_rustls = { package = "rusoto_core", version = "0.44", default_features = false, features=["rustls"], optional = true }
rusoto_dynamodb_default = { package = "rusoto_dynamodb", version = "0.44", optional = true }
rusoto_dynamodb_rustls = { package = "rusoto_dynamodb", version = "0.44", default_features = false, features=["rustls"], optional = true }
uuid = { version = "0.8", features = ["v4"], optional = true }
chrono = { version = "0.4", optional = true }
[dev-dependencies]
...
serde_json = "1.0"
tokio = { version = "0.2", features = ["macros"] }
lambda_http = { git = "https://github.com/awslabs/aws-lambda-rust-runtime/", branch = "master"}
[features]
default = ["uuid", "chrono", "derive", "rusoto_core_default", "rusoto_dynamodb_default"]
rustls = ["uuid", "chrono", "derive", "rusoto_core_rustls", "rusoto_dynamodb_rustls"]
derive = ["dynomite-derive"]
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 why
If 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 ..
Tip: to discover all features offered by a crate check its Cargo.toml file.
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:
- https://github.com/softprops/dynomite/blob/master/dynomite/Cargo.toml
- https://www.reddit.com/r/rust/comments/7o7ov7/can_someone_explain_how_features_work_in_cargo/
- https://docs.rs/dynomite/0.8.2/dynomite/#rustls
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.