Document that nightly features should be opt-in using a --cfg flag
#284
Conversation
|
This PR was prompted by https://rust-lang.zulipchat.com/#narrow/channel/233931-t-compiler.2Fmajor-changes/topic/document.20RUSTC_BOOTSTRAP.20in.20the.20unstable.20.E2.80.A6.20compiler-team.23863/with/512532020. That discussion is long and most of it is not relevant; but maybe it's helpful context. |
|
oh - |
|
I personally prefer not to use the Cargo feature for this purpose (and use cfg instead), as it is easy to get into trouble if there is a crate enabling it somewhere in the dependency graph. One of the real world examples where Cargo feature based approach was a problem was crossbeam-rs/crossbeam#435 where people encountered a problem and talked negatively about dependence on nightly-specific features (looking at some of the issues linked from there, it seems they thought it was automatically enabled), but it was actually opt-in feature and it was themselves or their other dependencies that actually opt-in-ed that feature. See also rayon-rs/rayon#369, rayon-rs/rayon#364, tokio-rs/tokio#1774 (comment), https://github.com/dtolnay/proc-macro2#unstable-features, etc. for other discussions on using cfg instead of Cargo features for this or similar purpose. |
jyn514
changed the title
--cfg flag
src/future-proofing.md
Outdated
| Some libraries need to use, or want to experiment with, the [nightly channel]. | ||
| To avoid accidental breakage, libraries should either: | ||
| - Use nightly features unconditionally, so that people depending on the library must always use a nightly toolchain to build | ||
| - Add a `--cfg` flag which opts-in to the nightly features (optionally, with feature detection to verify the features are present in the current compiler version). This allows people to avoid opting-in if they do not want to be exposed to possible breakage. |
There was a problem hiding this comment.
| - Add a `--cfg` flag which opts-in to the nightly features (optionally, with feature detection to verify the features are present in the current compiler version). This allows people to avoid opting-in if they do not want to be exposed to possible breakage. | |
| - Add a `--cfg` flag which opts-in to the nightly features (optionally, with a test compilation to provide better error messages from opt-in when feature is not supported). This allows people to avoid opting-in if they do not want to be exposed to possible breakage. |
There was a problem hiding this comment.
Perhaps something like this? It's a stronger statement and less likely to be misread in a way that suggests avoiding the explicit opt-in.
There was a problem hiding this comment.
sure, i added something along those lines.
|
👋 this is ready for review :) |
This was discussed (a long time ago now) in #95. I tried to make this a simple summary of that discussion and not editorialize too much. I did add a note on just running
rustc --version, since that's nearly always broken.I chose
intrinsics::[black_box, catch_unwind}as the examples because a) they already have stable versions, so there's no temptation to copy them out of the docs, and b) intrinsics are perma-unstable and we won't need to update them.