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}
cargo_platform/lib.rs

cargo_platform/
lib.rs
