compiler/rustc_feature/src/lib.rs

   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 `librustc_ast_passes/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(once_cell)]
  15
  16 mod accepted;
  17 mod active;
  18 mod builtin_attrs;
  19 mod removed;
  20
  21 use rustc_span::{edition::Edition, symbol::Symbol, Span};
  22 use std::fmt;
  23 use std::num::NonZeroU32;
  24
  25 #[derive(Clone, Copy)]
  26 pub enum State {
  27     Accepted,
  28     Active { set: fn(&mut Features, Span) },
  29     Removed { reason: Option<&'static str> },
  30     Stabilized { reason: Option<&'static str> },
  31 }
  32
  33 impl fmt::Debug for State {
  34     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
  35         match self {
  36             State::Accepted { .. } => write!(f, "accepted"),
  37             State::Active { .. } => write!(f, "active"),
  38             State::Removed { .. } => write!(f, "removed"),
  39             State::Stabilized { .. } => write!(f, "stabilized"),
  40         }
  41     }
  42 }
  43
  44 #[derive(Debug, Clone)]
  45 pub struct Feature {
  46     pub state: State,
  47     pub name: Symbol,
  48     pub since: &'static str,
  49     issue: Option<NonZeroU32>,
  50     pub edition: Option<Edition>,
  51     description: &'static str,
  52 }
  53
  54 #[derive(Copy, Clone, Debug)]
  55 pub enum Stability {
  56     Unstable,
  57     // First argument is tracking issue link; second argument is an optional
  58     // help message, which defaults to "remove this attribute".
  59     Deprecated(&'static str, Option<&'static str>),
  60 }
  61
  62 #[derive(Clone, Copy, Debug, Hash)]
  63 pub enum UnstableFeatures {
  64     /// Hard errors for unstable features are active, as on beta/stable channels.
  65     Disallow,
  66     /// Allow features to be activated, as on nightly.
  67     Allow,
  68     /// Errors are bypassed for bootstrapping. This is required any time
  69     /// during the build that feature-related lints are set to warn or above
  70     /// because the build turns on warnings-as-errors and uses lots of unstable
  71     /// features. As a result, this is always required for building Rust itself.
  72     Cheat,
  73 }
  74
  75 impl UnstableFeatures {
  76     /// This takes into account `RUSTC_BOOTSTRAP`.
  77     ///
  78     /// If `krate` is [`Some`], then setting `RUSTC_BOOTSTRAP=krate` will enable the nightly features.
  79     /// Otherwise, only `RUSTC_BOOTSTRAP=1` will work.
  80     pub fn from_environment(krate: Option<&str>) -> Self {
  81         // `true` if this is a feature-staged build, i.e., on the beta or stable channel.
  82         let disable_unstable_features = option_env!("CFG_DISABLE_UNSTABLE_FEATURES").is_some();
  83         // Returns whether `krate` should be counted as unstable
  84         let is_unstable_crate = |var: &str| {
  85             krate.map_or(false, |name| var.split(',').any(|new_krate| new_krate == name))
  86         };
  87         // `true` if we should enable unstable features for bootstrapping.
  88         let bootstrap = std::env::var("RUSTC_BOOTSTRAP")
  89             .map_or(false, |var| var == "1" || is_unstable_crate(&var));
  90         match (disable_unstable_features, bootstrap) {
  91             (_, true) => UnstableFeatures::Cheat,
  92             (true, _) => UnstableFeatures::Disallow,
  93             (false, _) => UnstableFeatures::Allow,
  94         }
  95     }
  96
  97     pub fn is_nightly_build(&self) -> bool {
  98         match *self {
  99             UnstableFeatures::Allow | UnstableFeatures::Cheat => true,
 100             UnstableFeatures::Disallow => false,
 101         }
 102     }
 103 }
 104
 105 fn find_lang_feature_issue(feature: Symbol) -> Option<NonZeroU32> {
 106     if let Some(info) = ACTIVE_FEATURES.iter().find(|t| t.name == feature) {
 107         // FIXME (#28244): enforce that active features have issue numbers
 108         // assert!(info.issue.is_some())
 109         info.issue
 110     } else {
 111         // search in Accepted, Removed, or Stable Removed features
 112         let found = ACCEPTED_FEATURES
 113             .iter()
 114             .chain(REMOVED_FEATURES)
 115             .chain(STABLE_REMOVED_FEATURES)
 116             .find(|t| t.name == feature);
 117         match found {
 118             Some(found) => found.issue,
 119             None => panic!("feature `{}` is not declared anywhere", feature),
 120         }
 121     }
 122 }
 123
 124 const fn to_nonzero(n: Option<u32>) -> Option<NonZeroU32> {
 125     // Can be replaced with `n.and_then(NonZeroU32::new)` if that is ever usable
 126     // in const context. Requires https://github.com/rust-lang/rfcs/pull/2632.
 127     match n {
 128         None => None,
 129         Some(n) => NonZeroU32::new(n),
 130     }
 131 }
 132
 133 pub enum GateIssue {
 134     Language,
 135     Library(Option<NonZeroU32>),
 136 }
 137
 138 pub fn find_feature_issue(feature: Symbol, issue: GateIssue) -> Option<NonZeroU32> {
 139     match issue {
 140         GateIssue::Language => find_lang_feature_issue(feature),
 141         GateIssue::Library(lib) => lib,
 142     }
 143 }
 144
 145 pub use accepted::ACCEPTED_FEATURES;
 146 pub use active::{Features, ACTIVE_FEATURES, INCOMPATIBLE_FEATURES, INCOMPLETE_FEATURES};
 147 pub use builtin_attrs::{
 148     deprecated_attributes, find_gated_cfg, is_builtin_attr_name, AttributeGate, AttributeTemplate,
 149     AttributeType, BuiltinAttribute, GatedCfg, BUILTIN_ATTRIBUTES, BUILTIN_ATTRIBUTE_MAP,
 150 };
 151 pub use removed::{REMOVED_FEATURES, STABLE_REMOVED_FEATURES};
 152
 153 #[cfg(test)]
 154 mod test {
 155     use super::UnstableFeatures;
 156
 157     #[test]
 158     fn rustc_bootstrap_parsing() {
 159         let is_bootstrap = |env, krate| {
 160             std::env::set_var("RUSTC_BOOTSTRAP", env);
 161             matches!(UnstableFeatures::from_environment(krate), UnstableFeatures::Cheat)
 162         };
 163         assert!(is_bootstrap("1", None));
 164         assert!(is_bootstrap("1", Some("x")));
 165         // RUSTC_BOOTSTRAP allows specifying a specific crate
 166         assert!(is_bootstrap("x", Some("x")));
 167         // RUSTC_BOOTSTRAP allows multiple comma-delimited crates
 168         assert!(is_bootstrap("x,y,z", Some("x")));
 169         assert!(is_bootstrap("x,y,z", Some("y")));
 170         // Crate that aren't specified do not get unstable features
 171         assert!(!is_bootstrap("x", Some("a")));
 172         assert!(!is_bootstrap("x,y,z", Some("a")));
 173         assert!(!is_bootstrap("x,y,z", None));
 174
 175         // this is technically a breaking change, but there are no stability guarantees for RUSTC_BOOTSTRAP
 176         assert!(!is_bootstrap("0", None));
 177     }
 178 }