1 //! # Feature gates
2 //!
3 //! This crate declares the set of past and present unstable features in the compiler.
4 //! Feature gate checking itself is done in `rustc_ast_passes/src/feature_gate.rs`
5 //! at the moment.
6 //!
7 //! Features are enabled in programs via the crate-level attributes of
8 //! `#![feature(...)]` with a comma-separated list of features.
9 //!
10 //! For the purpose of future feature-tracking, once a feature gate is added,
11 //! even if it is stabilized or removed, *do not remove it*. Instead, move the
12 //! symbol to the `accepted` or `removed` modules respectively.
13
14 #![feature(lazy_cell)]
15 #![deny(rustc::untranslatable_diagnostic)]
16 #![deny(rustc::diagnostic_outside_of_impl)]
17
18 mod accepted;
19 mod active;
20 mod builtin_attrs;
21 mod removed;
22
23 #[cfg(test)]
24 mod tests;
25
26 use rustc_span::{edition::Edition, symbol::Symbol, Span};
27 use std::fmt;
28 use std::num::NonZeroU32;
29
30 #[derive(Clone, Copy)]
31 pub enum State {
32 Accepted,
33 Active { set: fn(&mut Features, Span) },
34 Removed { reason: Option<&'static str> },
35 Stabilized { reason: Option<&'static str> },
36 }
37
38 impl fmt::Debug for State {
fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result39 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
40 match self {
41 State::Accepted { .. } => write!(f, "accepted"),
42 State::Active { .. } => write!(f, "active"),
43 State::Removed { .. } => write!(f, "removed"),
44 State::Stabilized { .. } => write!(f, "stabilized"),
45 }
46 }
47 }
48
49 #[derive(Debug, Clone)]
50 pub struct Feature {
51 pub state: State,
52 pub name: Symbol,
53 pub since: &'static str,
54 issue: Option<NonZeroU32>,
55 pub edition: Option<Edition>,
56 }
57
58 #[derive(Copy, Clone, Debug)]
59 pub enum Stability {
60 Unstable,
61 // First argument is tracking issue link; second argument is an optional
62 // help message, which defaults to "remove this attribute".
63 Deprecated(&'static str, Option<&'static str>),
64 }
65
66 #[derive(Clone, Copy, Debug, Hash)]
67 pub enum UnstableFeatures {
68 /// Hard errors for unstable features are active, as on beta/stable channels.
69 Disallow,
70 /// Allow features to be activated, as on nightly.
71 Allow,
72 /// Errors are bypassed for bootstrapping. This is required any time
73 /// during the build that feature-related lints are set to warn or above
74 /// because the build turns on warnings-as-errors and uses lots of unstable
75 /// features. As a result, this is always required for building Rust itself.
76 Cheat,
77 }
78
79 impl UnstableFeatures {
80 /// This takes into account `RUSTC_BOOTSTRAP`.
81 ///
82 /// If `krate` is [`Some`], then setting `RUSTC_BOOTSTRAP=krate` will enable the nightly features.
83 /// Otherwise, only `RUSTC_BOOTSTRAP=1` will work.
from_environment(krate: Option<&str>) -> Self84 pub fn from_environment(krate: Option<&str>) -> Self {
85 // `true` if this is a feature-staged build, i.e., on the beta or stable channel.
86 let disable_unstable_features =
87 option_env!("CFG_DISABLE_UNSTABLE_FEATURES").is_some_and(|s| s != "0");
88 // Returns whether `krate` should be counted as unstable
89 let is_unstable_crate =
90 |var: &str| krate.is_some_and(|name| var.split(',').any(|new_krate| new_krate == name));
91 // `true` if we should enable unstable features for bootstrapping.
92 let bootstrap =
93 std::env::var("RUSTC_BOOTSTRAP").is_ok_and(|var| var == "1" || is_unstable_crate(&var));
94 match (disable_unstable_features, bootstrap) {
95 (_, true) => UnstableFeatures::Cheat,
96 (true, _) => UnstableFeatures::Disallow,
97 (false, _) => UnstableFeatures::Allow,
98 }
99 }
100
is_nightly_build(&self) -> bool101 pub fn is_nightly_build(&self) -> bool {
102 match *self {
103 UnstableFeatures::Allow | UnstableFeatures::Cheat => true,
104 UnstableFeatures::Disallow => false,
105 }
106 }
107 }
108
find_lang_feature_issue(feature: Symbol) -> Option<NonZeroU32>109 fn find_lang_feature_issue(feature: Symbol) -> Option<NonZeroU32> {
110 if let Some(info) = ACTIVE_FEATURES.iter().find(|t| t.name == feature) {
111 // FIXME (#28244): enforce that active features have issue numbers
112 // assert!(info.issue.is_some())
113 info.issue
114 } else {
115 // search in Accepted, Removed, or Stable Removed features
116 let found = ACCEPTED_FEATURES
117 .iter()
118 .chain(REMOVED_FEATURES)
119 .chain(STABLE_REMOVED_FEATURES)
120 .find(|t| t.name == feature);
121 match found {
122 Some(found) => found.issue,
123 None => panic!("feature `{feature}` is not declared anywhere"),
124 }
125 }
126 }
127
to_nonzero(n: Option<u32>) -> Option<NonZeroU32>128 const fn to_nonzero(n: Option<u32>) -> Option<NonZeroU32> {
129 // Can be replaced with `n.and_then(NonZeroU32::new)` if that is ever usable
130 // in const context. Requires https://github.com/rust-lang/rfcs/pull/2632.
131 match n {
132 None => None,
133 Some(n) => NonZeroU32::new(n),
134 }
135 }
136
137 pub enum GateIssue {
138 Language,
139 Library(Option<NonZeroU32>),
140 }
141
find_feature_issue(feature: Symbol, issue: GateIssue) -> Option<NonZeroU32>142 pub fn find_feature_issue(feature: Symbol, issue: GateIssue) -> Option<NonZeroU32> {
143 match issue {
144 GateIssue::Language => find_lang_feature_issue(feature),
145 GateIssue::Library(lib) => lib,
146 }
147 }
148
149 pub use accepted::ACCEPTED_FEATURES;
150 pub use active::{Features, ACTIVE_FEATURES, INCOMPATIBLE_FEATURES};
151 pub use builtin_attrs::AttributeDuplicates;
152 pub use builtin_attrs::{
153 deprecated_attributes, find_gated_cfg, is_builtin_attr_name, is_builtin_only_local,
154 is_valid_for_get_attr, AttributeGate, AttributeTemplate, AttributeType, BuiltinAttribute,
155 GatedCfg, BUILTIN_ATTRIBUTES, BUILTIN_ATTRIBUTE_MAP,
156 };
157 pub use removed::{REMOVED_FEATURES, STABLE_REMOVED_FEATURES};
158