Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed
rimutaka opened this issue Jun 29, 2020 · 1 comment · Fixed by #8997
Closed

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

rimutaka opened this issue Jun 29, 2020 · 1 comment · Fixed by #8997
Labels
A-documenting-cargo-itself Area: Cargo's documentation A-features Area: features — conditional compilation

Comments

@rimutaka
Copy link
Contributor

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.

@rimutaka rimutaka added the C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` label Jun 29, 2020
@ehuss ehuss added A-documenting-cargo-itself Area: Cargo's documentation A-features Area: features — conditional compilation and removed C-feature-request Category: proposal for a feature. Before PR, ping rust-lang/cargo if this is not `Feature accepted` labels Jul 29, 2020
@ehuss
Copy link
Contributor

ehuss commented Dec 18, 2020

@rimutaka Thanks for publishing the blog post. In #8997 I have posted a rewrite of the features chapter that attempts to go into a little more detail. If you could take a look at it, I would appreciate any feedback you can give.

@bors bors closed this as completed in #8997 Jan 5, 2021
@bors bors closed this as completed in 4aa5223 Jan 5, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-documenting-cargo-itself Area: Cargo's documentation A-features Area: features — conditional compilation
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants