Skip to content

Add some hints to the docs for cfg() targets #6990

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.

Sign up for GitHub

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

Merged
merged 3 commits into from
May 28, 2019
Merged

Add some hints to the docs for cfg() targets #6990

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
03294f8
Add some hints to the docs for `cfg()` targets
notriddle May 27, 2019
f2663ba
Update specifying-dependencies.md
notriddle May 28, 2019
69f9adb
Link cfg, remove old note, fix link.
ehuss May 28, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions src/doc/src/reference/specifying-dependencies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -461,6 +461,19 @@ Like with Rust, the syntax here supports the `not`, `any`, and `all` operators
to combine various cfg name/value pairs. Note that the `cfg` syntax has only
been available since Cargo 0.9.0 (Rust 1.8.0).

If you want to know which cfg targets are available on your platform, run
`rustc --print=cfg` from the command line. If you want to know which `cfg`
targets are available for another platform, such as 64-bit Windows,
run `rustc --print=cfg --target=x86_64-pc-windows-msvc`.
If you want to know which cfg targets are used by the release profile,
add the `-O` parameter.

This same set of values is used throughout the build for all crates in your project,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a little confused by how this is worded. Instead of trying to explain why it works this way, I would just be direct and say cfg(feature = "foo") cannot be used in the [target] table, with a link to the [features] section. Similarly test, proc-macro, and debug-assertions do not work either, though I'm not sure if it is worthwhile to list everything that does or does not work.

Copy link
Contributor Author

@notriddle notriddle May 28, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not wanting to list all of the configuration options is the reason I tried to explain why it works this way. Between giving a mechanical explanation of why feature flags don't work, and pointing the user at --print=cfg, I figured those would allow the user to figure out which options work and which options don't.

I stripped it out, though. Let me know if you can think of a better way to do this.

so, unlike in your Rust source code,
you cannot use `[target.'cfg(feature = "my_crate")'.dependencies]` to add
dependencies based on optional crate features.
Use [the `[features]` section](manifest.md#the-features-section) instead.

In addition to `#[cfg]` syntax, Cargo also supports listing out the full target
the dependencies would apply to:

Expand Down