Skip to content

Add more examples with explanations to Ch 3.4. Features - help offered #8431

Closed
@rimutaka

Description

@rimutaka

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

  1. 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:

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions