#
cargo_platform/
lib.rs

    1//! Platform definition used by Cargo.
    2//!
    3//! This defines a [`Platform`] type which is used in Cargo to specify a target platform.
    4//! There are two kinds, a named target like `x86_64-apple-darwin`, and a "cfg expression"
    5//! like `cfg(any(target_os = "macos", target_os = "ios"))`.
    6//!
    7//! See `examples/matches.rs` for an example of how to match against a `Platform`.
    8//!
    9//! > This crate is maintained by the Cargo team for use by the wider
    10//! > ecosystem. This crate follows semver compatibility for its APIs.
    11//!
    12//! [`Platform`]: enum.Platform.html
    13
    14use std::str::FromStr;
    15use std::{fmt, path::Path};
    16
    17mod cfg;
    18mod error;
    19
    20use cfg::KEYWORDS;
    21pub use cfg::{Cfg, CfgExpr, Ident};
    22pub use error::{ParseError, ParseErrorKind};
    23
    24/// Platform definition.
    25#[derive(Eq, PartialEq, Hash, Ord, PartialOrd, Clone, Debug)]
    26pub enum Platform {
    27    /// A named platform, like `x86_64-apple-darwin`.
    28    Name(String),
    29    /// A cfg expression, like `cfg(windows)`.
    30    Cfg(CfgExpr),
    31}
    32
    33impl Platform {
    34    /// Returns whether the Platform matches the given target and cfg.
    35    ///
    36    /// The named target and cfg values should be obtained from `rustc`.
    37    pub fn matches(&self, name: &str, cfg: &[Cfg]) -> bool {
    38        match *self {
    39            Platform::Name(ref p) => p == name,
    40            Platform::Cfg(ref p) => p.matches(cfg),
    41        }
    42    }
    43
    44    fn validate_named_platform(name: &str) -> Result<(), ParseError> {
    45        if let Some(ch) = name
    46            .chars()
    47            .find(|&c| !(c.is_alphanumeric() || c == '_' || c == '-' || c == '.'))
    48        {
    49            if name.chars().any(|c| c == '(') {
    50                return Err(ParseError::new(
    51                    name,
    52                    ParseErrorKind::InvalidTarget(
    53                        "unexpected `(` character, cfg expressions must start with `cfg(`"
    54                            .to_string(),
    55                    ),
    56                ));
    57            }
    58            return Err(ParseError::new(
    59                name,
    60                ParseErrorKind::InvalidTarget(format!(
    61                    "unexpected character {} in target name",
    62                    ch
    63                )),
    64            ));
    65        }
    66        Ok(())
    67    }
    68
    69    pub fn check_cfg_attributes(&self, warnings: &mut Vec<String>) {
    70        fn check_cfg_expr(expr: &CfgExpr, warnings: &mut Vec<String>) {
    71            match *expr {
    72                CfgExpr::Not(ref e) => check_cfg_expr(e, warnings),
    73                CfgExpr::All(ref e) | CfgExpr::Any(ref e) => {
    74                    for e in e {
    75                        check_cfg_expr(e, warnings);
    76                    }
    77                }
    78                CfgExpr::Value(ref e) => match e {
    79                    Cfg::Name(name) => match name.as_str() {
    80                        "test" | "debug_assertions" | "proc_macro" =>
    81                            warnings.push(format!(
    82                                "Found `{}` in `target.'cfg(...)'.dependencies`. \
    83                                 This value is not supported for selecting dependencies \
    84                                 and will not work as expected. \
    85                                 To learn more visit \
    86                                 https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies",
    87                                 name
    88                            )),
    89                        _ => (),
    90                    },
    91                    Cfg::KeyPair(name, _) => if name.as_str() == "feature" {
    92                        warnings.push(String::from(
    93                            "Found `feature = ...` in `target.'cfg(...)'.dependencies`. \
    94                             This key is not supported for selecting dependencies \
    95                             and will not work as expected. \
    96                             Use the [features] section instead: \
    97                             https://doc.rust-lang.org/cargo/reference/features.html"
    98                        ))
    99                    },
    100                }
    101                CfgExpr::True | CfgExpr::False => {},
    102            }
    103        }
    104
    105        if let Platform::Cfg(cfg) = self {
    106            check_cfg_expr(cfg, warnings);
    107        }
    108    }
    109
    110    pub fn check_cfg_keywords(&self, warnings: &mut Vec<String>, path: &Path) {
    111        fn check_cfg_expr(expr: &CfgExpr, warnings: &mut Vec<String>, path: &Path) {
    112            match *expr {
    113                CfgExpr::Not(ref e) => check_cfg_expr(e, warnings, path),
    114                CfgExpr::All(ref e) | CfgExpr::Any(ref e) => {
    115                    for e in e {
    116                        check_cfg_expr(e, warnings, path);
    117                    }
    118                }
    119                CfgExpr::True | CfgExpr::False => {}
    120                CfgExpr::Value(ref e) => match e {
    121                    Cfg::Name(name) | Cfg::KeyPair(name, _) => {
    122                        if !name.raw && KEYWORDS.contains(&name.as_str()) {
    123                            warnings.push(format!(
    124                                "[{}] future-incompatibility: `cfg({e})` is deprecated as `{name}` is a keyword \
    125                                 and not an identifier and should not have have been accepted in this position.\n \
    126                                 | this was previously accepted by Cargo but is being phased out; it will become a hard error in a future release!\n \
    127                                 |\n \
    128                                 | help: use raw-idents instead: `cfg(r#{name})`",
    129                                 path.display()
    130                            ));
    131                        }
    132                    }
    133                },
    134            }
    135        }
    136
    137        if let Platform::Cfg(cfg) = self {
    138            check_cfg_expr(cfg, warnings, path);
    139        }
    140    }
    141}
    142
    143impl serde::Serialize for Platform {
    144    fn serialize<S>(&self, s: S) -> Result<S::Ok, S::Error>
    145    where
    146        S: serde::Serializer,
    147    {
    148        self.to_string().serialize(s)
    149    }
    150}
    151
    152impl<'de> serde::Deserialize<'de> for Platform {
    153    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    154    where
    155        D: serde::Deserializer<'de>,
    156    {
    157        let s = String::deserialize(deserializer)?;
    158        FromStr::from_str(&s).map_err(serde::de::Error::custom)
    159    }
    160}
    161
    162impl FromStr for Platform {
    163    type Err = ParseError;
    164
    165    fn from_str(s: &str) -> Result<Platform, ParseError> {
    166        if let Some(s) = s.strip_prefix("cfg(").and_then(|s| s.strip_suffix(')')) {
    167            s.parse().map(Platform::Cfg)
    168        } else {
    169            Platform::validate_named_platform(s)?;
    170            Ok(Platform::Name(s.to_string()))
    171        }
    172    }
    173}
    174
    175impl fmt::Display for Platform {
    176    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    177        match *self {
    178            Platform::Name(ref n) => n.fmt(f),
    179            Platform::Cfg(ref e) => write!(f, "cfg({})", e),
    180        }
    181    }
    182}