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 `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(once_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 {
  39     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.
  84     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").map(|s| s != "0").unwrap_or(false);
  88         // Returns whether `krate` should be counted as unstable
  89         let is_unstable_crate = |var: &str| {
  90             krate.map_or(false, |name| var.split(',').any(|new_krate| new_krate == name))
  91         };
  92         // `true` if we should enable unstable features for bootstrapping.
  93         let bootstrap = std::env::var("RUSTC_BOOTSTRAP")
  94             .map_or(false, |var| var == "1" || is_unstable_crate(&var));
  95         match (disable_unstable_features, bootstrap) {
  96             (_, true) => UnstableFeatures::Cheat,
  97             (true, _) => UnstableFeatures::Disallow,
  98             (false, _) => UnstableFeatures::Allow,
  99         }
 100     }
 101
 102     pub fn is_nightly_build(&self) -> bool {
 103         match *self {
 104             UnstableFeatures::Allow | UnstableFeatures::Cheat => true,
 105             UnstableFeatures::Disallow => false,
 106         }
 107     }
 108 }
 109
 110 fn find_lang_feature_issue(feature: Symbol) -> Option<NonZeroU32> {
 111     if let Some(info) = ACTIVE_FEATURES.iter().find(|t| t.name == feature) {
 112         // FIXME (#28244): enforce that active features have issue numbers
 113         // assert!(info.issue.is_some())
 114         info.issue
 115     } else {
 116         // search in Accepted, Removed, or Stable Removed features
 117         let found = ACCEPTED_FEATURES
 118             .iter()
 119             .chain(REMOVED_FEATURES)
 120             .chain(STABLE_REMOVED_FEATURES)
 121             .find(|t| t.name == feature);
 122         match found {
 123             Some(found) => found.issue,
 124             None => panic!("feature `{feature}` is not declared anywhere"),
 125         }
 126     }
 127 }
 128
 129 const fn to_nonzero(n: Option<u32>) -> Option<NonZeroU32> {
 130     // Can be replaced with `n.and_then(NonZeroU32::new)` if that is ever usable
 131     // in const context. Requires https://github.com/rust-lang/rfcs/pull/2632.
 132     match n {
 133         None => None,
 134         Some(n) => NonZeroU32::new(n),
 135     }
 136 }
 137
 138 pub enum GateIssue {
 139     Language,
 140     Library(Option<NonZeroU32>),
 141 }
 142
 143 pub fn find_feature_issue(feature: Symbol, issue: GateIssue) -> Option<NonZeroU32> {
 144     match issue {
 145         GateIssue::Language => find_lang_feature_issue(feature),
 146         GateIssue::Library(lib) => lib,
 147     }
 148 }
 149
 150 pub use accepted::ACCEPTED_FEATURES;
 151 pub use active::{Features, ACTIVE_FEATURES, INCOMPATIBLE_FEATURES};
 152 pub use builtin_attrs::AttributeDuplicates;
 153 pub use builtin_attrs::{
 154     deprecated_attributes, find_gated_cfg, is_builtin_attr_name, is_builtin_only_local,
 155     is_valid_for_get_attr, AttributeGate, AttributeTemplate, AttributeType, BuiltinAttribute,
 156     GatedCfg, BUILTIN_ATTRIBUTES, BUILTIN_ATTRIBUTE_MAP,
 157 };
 158 pub use removed::{REMOVED_FEATURES, STABLE_REMOVED_FEATURES};