target_spec/

summaries.rs

// Copyright (c) The cargo-guppy Contributors
// SPDX-License-Identifier: MIT OR Apache-2.0

//! Serialized versions of platform and target features.
//!
//! Some users of `target-spec` may want to serialize and deserialize its data structures into, say,
//! TOML files. This module provides facilities for that.
//!
//! Summaries require the `summaries` feature to be enabled.

use crate::{Error, Platform, TargetFeatures};
use serde::{Deserialize, Serialize};
use std::{borrow::Cow, collections::BTreeSet};

impl Platform {
    /// Converts this `Platform` to a serializable form.
    ///
    /// Requires the `summaries` feature to be enabled.
    #[inline]
    pub fn to_summary(&self) -> PlatformSummary {
        PlatformSummary::from_platform(self)
    }
}

/// An owned, serializable version of [`Platform`].
///
/// This structure can be serialized and deserialized using `serde`.
///
/// Requires the `summaries` feature to be enabled.
#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
#[serde(rename_all = "kebab-case")]
#[non_exhaustive]
pub struct PlatformSummary {
    /// The platform triple.
    pub triple: String,

    /// JSON for custom platforms.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub custom_json: Option<String>,

    /// `rustc --print=cfg` output for custom platforms.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub custom_cfg: Option<String>,

    /// The target features used.
    pub target_features: TargetFeaturesSummary,

    /// The flags enabled.
    #[serde(skip_serializing_if = "BTreeSet::is_empty", default)]
    pub flags: BTreeSet<String>,
}

impl PlatformSummary {
    /// Creates a new `PlatformSummary` with the provided triple and default options.
    ///
    /// The default options are:
    ///
    /// * `custom_json` is set to `None`.
    /// * `custom_cfg` is set to `None`.
    /// * `target_features` is set to [`TargetFeaturesSummary::Unknown`].
    /// * `flags` is empty.
    pub fn new(triple_str: impl Into<String>) -> Self {
        Self {
            triple: triple_str.into(),
            custom_json: None,
            custom_cfg: None,
            target_features: TargetFeaturesSummary::Unknown,
            flags: BTreeSet::new(),
        }
    }

    /// If this represents a custom platform, sets the target
    /// definition JSON for it.
    ///
    /// This clears any previously set `custom_cfg`, since only
    /// one custom platform source is allowed.
    ///
    /// For more about target definition JSON, see [Creating a
    /// custom
    /// target](https://docs.rust-embedded.org/embedonomicon/custom-target.html)
    /// in the Rust Embedonomicon.
    pub fn with_custom_json(mut self, custom_json: impl Into<String>) -> Self {
        self.custom_json = Some(custom_json.into());
        self.custom_cfg = None;
        self
    }

    /// If this represents a custom platform created from
    /// `rustc --print=cfg` output, sets that output.
    ///
    /// This clears any previously set `custom_json`, since only
    /// one custom platform source is allowed.
    pub fn with_custom_cfg(mut self, custom_cfg: impl Into<String>) -> Self {
        self.custom_cfg = Some(custom_cfg.into());
        self.custom_json = None;
        self
    }

    /// Sets the target features for this platform.
    pub fn with_target_features(mut self, target_features: TargetFeaturesSummary) -> Self {
        self.target_features = target_features;
        self
    }

    /// Adds flags for this platform.
    pub fn with_added_flags(mut self, flags: impl IntoIterator<Item = impl Into<String>>) -> Self {
        self.flags.extend(flags.into_iter().map(|flag| flag.into()));
        self
    }

    /// Creates a new `PlatformSummary` instance from a platform.
    pub fn from_platform(platform: &Platform) -> Self {
        Self {
            triple: platform.triple_str().to_string(),
            custom_json: platform.custom_json().map(|s| s.to_owned()),
            custom_cfg: platform.custom_cfg_text().map(|s| s.to_owned()),
            target_features: TargetFeaturesSummary::new(platform.target_features()),
            flags: platform.flags().map(|flag| flag.to_string()).collect(),
        }
    }

    /// Converts `self` to a `Platform`.
    ///
    /// Returns an `Error` if the platform was unknown.
    pub fn to_platform(&self) -> Result<Platform, Error> {
        if self.custom_json.is_some() && self.custom_cfg.is_some() {
            return Err(Error::CustomPlatformCreate(
                crate::errors::CustomTripleCreateError::ConflictingCustomPlatformSources {
                    triple: self.triple.clone(),
                },
            ));
        }

        #[allow(unused_variables)] // in some feature branches, json/cfg aren't used
        let mut platform = if let Some(json) = &self.custom_json {
            #[cfg(not(feature = "custom"))]
            return Err(Error::CustomPlatformCreate(
                crate::errors::CustomTripleCreateError::CustomJsonUnavailable,
            ));

            #[cfg(feature = "custom")]
            Platform::new_custom(
                self.triple.to_owned(),
                json,
                self.target_features.to_target_features(),
            )?
        } else if let Some(cfg_text) = &self.custom_cfg {
            #[cfg(not(feature = "custom-cfg"))]
            return Err(Error::CustomPlatformCreate(
                crate::errors::CustomTripleCreateError::CustomCfgUnavailable,
            ));

            #[cfg(feature = "custom-cfg")]
            Platform::new_custom_cfg(
                self.triple.to_owned(),
                cfg_text,
                self.target_features.to_target_features(),
            )?
        } else {
            Platform::new(
                self.triple.to_owned(),
                self.target_features.to_target_features(),
            )?
        };

        platform.add_flags(self.flags.iter().cloned());
        Ok(platform)
    }
}

/// An owned, serializable version of [`TargetFeatures`].
///
/// This type can be serialized and deserialized using `serde`.
///
/// Requires the `summaries` feature to be enabled.
#[derive(Clone, Debug, Eq, PartialEq)]
#[non_exhaustive]
#[derive(Default)]
pub enum TargetFeaturesSummary {
    /// The target features are unknown.
    ///
    /// This is the default.
    #[default]
    Unknown,
    /// Only match the specified features.
    Features(BTreeSet<String>),
    /// Match all features.
    All,
}

impl TargetFeaturesSummary {
    /// Creates a new `TargetFeaturesSummary` from a `TargetFeatures`.
    pub fn new(target_features: &TargetFeatures) -> Self {
        match target_features {
            TargetFeatures::Unknown => TargetFeaturesSummary::Unknown,
            TargetFeatures::Features(features) => TargetFeaturesSummary::Features(
                features.iter().map(|feature| feature.to_string()).collect(),
            ),
            TargetFeatures::All => TargetFeaturesSummary::All,
        }
    }

    /// Converts `self` to a `TargetFeatures` instance.
    pub fn to_target_features(&self) -> TargetFeatures {
        match self {
            TargetFeaturesSummary::Unknown => TargetFeatures::Unknown,
            TargetFeaturesSummary::All => TargetFeatures::All,
            TargetFeaturesSummary::Features(features) => {
                let features = features
                    .iter()
                    .map(|feature| Cow::Owned(feature.clone()))
                    .collect();
                TargetFeatures::Features(features)
            }
        }
    }
}

mod platform_impl {
    use super::*;
    use serde::{
        Deserializer,
        de::{self, MapAccess, Visitor, value::MapAccessDeserializer},
    };
    use std::fmt;

    impl<'de> Deserialize<'de> for PlatformSummary {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            deserializer.deserialize_any(PlatformSummaryVisitor)
        }
    }

    // This is a hand-written visitor and not serde(untagged) for better error
    // messages.
    struct PlatformSummaryVisitor;

    impl<'de> Visitor<'de> for PlatformSummaryVisitor {
        type Value = PlatformSummary;

        fn expecting(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
            f.write_str("a platform (a triple string or a table with a `triple` key)")
        }

        fn visit_str<E>(self, triple: &str) -> Result<Self::Value, E>
        where
            E: de::Error,
        {
            validate_triple(triple)?;
            Ok(PlatformSummary::new(triple))
        }

        fn visit_map<A>(self, map: A) -> Result<Self::Value, A::Error>
        where
            A: MapAccess<'de>,
        {
            let PlatformSummaryTable {
                triple,
                custom_json,
                custom_cfg,
                target_features,
                flags,
            } = PlatformSummaryTable::deserialize(MapAccessDeserializer::new(map))?;
            validate_triple(&triple)?;
            Ok(PlatformSummary {
                triple,
                custom_json,
                custom_cfg,
                target_features,
                flags,
            })
        }
    }

    fn validate_triple<E: de::Error>(triple: &str) -> Result<(), E> {
        if triple.is_empty() {
            return Err(E::custom("a platform triple cannot be empty"));
        }
        Ok(())
    }

    #[derive(Deserialize)]
    #[serde(rename_all = "kebab-case", deny_unknown_fields)]
    struct PlatformSummaryTable {
        triple: String,
        #[serde(default)]
        custom_json: Option<String>,
        #[serde(default)]
        custom_cfg: Option<String>,
        #[serde(default)]
        target_features: TargetFeaturesSummary,
        #[serde(default)]
        flags: BTreeSet<String>,
    }
}

mod target_features_impl {
    use super::*;
    use serde::{Deserialize, Deserializer, Serialize, Serializer, de::Error};

    impl Serialize for TargetFeaturesSummary {
        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
        where
            S: Serializer,
        {
            match self {
                TargetFeaturesSummary::Unknown => "unknown".serialize(serializer),
                TargetFeaturesSummary::All => "all".serialize(serializer),
                TargetFeaturesSummary::Features(features) => features.serialize(serializer),
            }
        }
    }

    impl<'de> Deserialize<'de> for TargetFeaturesSummary {
        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
        where
            D: Deserializer<'de>,
        {
            let d = TargetFeaturesDeserialize::deserialize(deserializer)?;
            match d {
                TargetFeaturesDeserialize::String(target_features) => {
                    match target_features.as_str() {
                        "unknown" => Ok(TargetFeaturesSummary::Unknown),
                        "all" => Ok(TargetFeaturesSummary::All),
                        other => Err(D::Error::custom(format!(
                            "unknown string for target features: {other}",
                        ))),
                    }
                }
                TargetFeaturesDeserialize::List(target_features) => {
                    Ok(TargetFeaturesSummary::Features(target_features))
                }
            }
        }
    }

    #[derive(Deserialize)]
    #[serde(untagged)]
    enum TargetFeaturesDeserialize {
        String(String),
        List(BTreeSet<String>),
    }
}

#[cfg(test)]
mod tests {
    #![allow(clippy::vec_init_then_push)]

    use super::*;

    #[test]
    fn platform_deserialize_valid() {
        // Need a wrapper because of TOML restrictions
        #[derive(Debug, Deserialize, Serialize, Eq, PartialEq)]
        struct Wrapper {
            platform: PlatformSummary,
        }

        let mut valid = vec![];
        valid.push((
            r#"platform = "x86_64-unknown-linux-gnu""#,
            PlatformSummary {
                triple: "x86_64-unknown-linux-gnu".into(),
                custom_json: None,
                custom_cfg: None,
                target_features: TargetFeaturesSummary::Unknown,
                flags: BTreeSet::new(),
            },
        ));
        valid.push((
            r#"platform = { triple = "x86_64-unknown-linux-gnu" }"#,
            PlatformSummary {
                triple: "x86_64-unknown-linux-gnu".into(),
                custom_json: None,
                custom_cfg: None,
                target_features: TargetFeaturesSummary::Unknown,
                flags: BTreeSet::new(),
            },
        ));
        valid.push((
            r#"platform = { triple = "x86_64-unknown-linux-gnu", target-features = "unknown" }"#,
            PlatformSummary {
                triple: "x86_64-unknown-linux-gnu".into(),
                custom_json: None,
                custom_cfg: None,
                target_features: TargetFeaturesSummary::Unknown,
                flags: BTreeSet::new(),
            },
        ));
        valid.push((
            r#"platform = { triple = "x86_64-unknown-linux-gnu", target-features = "all" }"#,
            PlatformSummary {
                triple: "x86_64-unknown-linux-gnu".into(),
                custom_json: None,
                custom_cfg: None,
                target_features: TargetFeaturesSummary::All,
                flags: BTreeSet::new(),
            },
        ));
        valid.push((
            r#"platform = { triple = "x86_64-unknown-linux-gnu", target-features = [] }"#,
            PlatformSummary {
                triple: "x86_64-unknown-linux-gnu".into(),
                custom_json: None,
                custom_cfg: None,
                target_features: TargetFeaturesSummary::Features(BTreeSet::new()),
                flags: BTreeSet::new(),
            },
        ));

        let custom_json = r#"{"arch":"x86_64","target-pointer-width":"64","llvm-target":"x86_64-unknown-haiku","data-layout":"e-m:e-p270:32:32-p271:32:32-p272:64:64-i64:64-f80:128-n8:16:32:64-S128","os":"haiku","abi":null,"env":null,"vendor":null,"families":[],"endian":"little","min-atomic-width":null,"max-atomic-width":64,"panic-strategy":"unwind"}"#;
        let toml = format!(
            r#"platform = {{ triple = "x86_64-unknown-haiku", custom-json = '{custom_json}' }}"#
        );

        valid.push((
            &toml,
            PlatformSummary {
                triple: "x86_64-unknown-haiku".into(),
                custom_json: Some(custom_json.to_owned()),
                custom_cfg: None,
                target_features: TargetFeaturesSummary::Unknown,
                flags: BTreeSet::new(),
            },
        ));

        let mut flags = BTreeSet::new();
        flags.insert("cargo_web".to_owned());
        valid.push((
            r#"platform = { triple = "x86_64-unknown-linux-gnu", flags = ["cargo_web"] }"#,
            PlatformSummary {
                triple: "x86_64-unknown-linux-gnu".into(),
                custom_json: None,
                custom_cfg: None,
                target_features: TargetFeaturesSummary::Unknown,
                flags,
            },
        ));

        let custom_cfg = indoc::indoc! {r#"
            panic="unwind"
            target_arch="x86_64"
            target_endian="little"
            target_env="gnu"
            target_family="unix"
            target_os="linux"
            target_pointer_width="64"
            target_vendor="unknown"
        "#};
        let toml_cfg = format!(
            "[platform]\n\
             triple = \"my-custom-linux\"\n\
             custom-cfg = '''\n\
             {custom_cfg}'''"
        );
        valid.push((
            &toml_cfg,
            PlatformSummary {
                triple: "my-custom-linux".into(),
                custom_json: None,
                custom_cfg: Some(custom_cfg.to_owned()),
                target_features: TargetFeaturesSummary::Unknown,
                flags: BTreeSet::new(),
            },
        ));

        for (input, expected) in valid {
            let actual: Wrapper =
                toml::from_str(input).unwrap_or_else(|err| panic!("input {input} is valid: {err}"));
            assert_eq!(actual.platform, expected, "for input: {input}");

            // Serialize and deserialize again.
            let serialized = toml::to_string(&actual).expect("serialized correctly");
            let actual_2: Wrapper = toml::from_str(&serialized)
                .unwrap_or_else(|err| panic!("serialized input: {input} is valid: {err}"));
            assert_eq!(actual, actual_2, "for input: {input}");

            // Check that custom JSON functionality works.
            if actual.platform.custom_json.is_some() {
                #[cfg(feature = "custom")]
                {
                    let platform = actual
                        .platform
                        .to_platform()
                        .expect("custom platform parsed successfully");
                    assert!(platform.is_custom(), "this is a custom platform");
                }

                #[cfg(not(feature = "custom"))]
                {
                    use crate::errors::CustomTripleCreateError;

                    let error = actual
                        .platform
                        .to_platform()
                        .expect_err("custom platforms are disabled");
                    assert!(matches!(
                        error,
                        Error::CustomPlatformCreate(CustomTripleCreateError::CustomJsonUnavailable)
                    ));
                }
            }

            // Check that custom cfg functionality works.
            if actual.platform.custom_cfg.is_some() {
                #[cfg(feature = "custom-cfg")]
                {
                    let platform = actual
                        .platform
                        .to_platform()
                        .expect("custom cfg platform parsed successfully");
                    assert!(platform.is_custom(), "this is a custom platform");
                }

                #[cfg(not(feature = "custom-cfg"))]
                {
                    use crate::errors::CustomTripleCreateError;

                    let error = actual
                        .platform
                        .to_platform()
                        .expect_err("custom cfg platforms are disabled");
                    assert!(matches!(
                        error,
                        Error::CustomPlatformCreate(CustomTripleCreateError::CustomCfgUnavailable)
                    ));
                }
            }
        }
    }
    #[test]
    fn platform_deserialize_errors() {
        #[derive(Debug, Deserialize)]
        struct Wrapper {
            #[allow(dead_code)]
            platform: PlatformSummary,
        }

        for (input, expected) in [
            (r#"platform = """#, "a platform triple cannot be empty"),
            (
                r#"platform = { triple = "" }"#,
                "a platform triple cannot be empty",
            ),
            (
                r#"platform = { target-features = [] }"#,
                "missing field `triple`",
            ),
            (
                r#"platform = { tripel = "x86_64-unknown-linux-gnu" }"#,
                "unknown field `tripel`",
            ),
            (
                r#"platform = { triple = "x86_64-unknown-linux-gnu", target-feature = ["sse2"] }"#,
                "unknown field `target-feature`",
            ),
            (
                r#"platform = { triple = "x86_64-unknown-linux-gnu", target-features = "bogus" }"#,
                "unknown string for target features: bogus",
            ),
            (
                "platform = 5",
                "expected a platform (a triple string or a table with a `triple` key)",
            ),
            (
                r#"platform = ["x86_64-unknown-linux-gnu"]"#,
                "expected a platform (a triple string or a table with a `triple` key)",
            ),
        ] {
            let message = toml::from_str::<Wrapper>(input)
                .expect_err("input rejected")
                .to_string();
            assert!(
                message.contains(expected),
                "for input {input}: error `{message}` contains `{expected}`",
            );
        }
    }
}

#[cfg(all(test, feature = "proptest1"))]
mod proptests {
    use super::*;
    use proptest::prelude::*;
    use std::collections::HashSet;

    proptest! {
        #[test]
        fn summary_roundtrip(platform in Platform::strategy(any::<TargetFeatures>())) {
            let summary = PlatformSummary::from_platform(&platform);
            let serialized = toml::ser::to_string(&summary).expect("serialization succeeded");

            let deserialized: PlatformSummary = toml::from_str(&serialized).expect("deserialization succeeded");
            assert_eq!(summary, deserialized, "summary and deserialized should match");
            let platform2 = deserialized.to_platform().expect("conversion to Platform succeeded");

            assert_eq!(platform.triple_str(), platform2.triple_str(), "triples match");
            assert_eq!(platform.target_features(), platform2.target_features(), "target features match");
            assert_eq!(platform.flags().collect::<HashSet<_>>(), platform2.flags().collect::<HashSet<_>>(), "flags match");
        }
    }
}