guppy/platform/
platform_spec.rs

1// Copyright (c) The cargo-guppy Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4#[allow(unused_imports)]
5use crate::platform::EnabledTernary;
6use crate::{errors::TargetSpecError, platform::Platform};
7use std::sync::Arc;
8
9/// A specifier for a set of platforms.
10///
11/// Some uses of `guppy` care about one or more specific platforms, and others
12/// care about queries against the intersection of all hypothetical platforms,
13/// or against a union of any of them. `PlatformSpec` represents this notion.
14///
15/// # Ordering
16///
17/// For any dependency status, the results of queries against these specs are
18/// ordered (by [`EnabledTernary`]'s `Ord` impl, where `Disabled < Unknown <
19/// Enabled`) as:
20///
21/// ```text
22/// Platforms([]) <= Always <= Platforms(non-empty) <= Any
23/// ```
24///
25/// `Platforms` over every known platform is still not the same as `Any`, since
26/// the latter also covers platforms that `guppy` does not know about.
27///
28/// `PlatformSpec` does not currently support expressions, but it might in the future, using an
29/// [SMT solver](https://en.wikipedia.org/wiki/Satisfiability_modulo_theories).
30#[derive(Clone, Debug)]
31#[non_exhaustive]
32pub enum PlatformSpec {
33    /// The intersection of all platforms.
34    ///
35    /// Dependency queries performed against this variant will return [`EnabledTernary::Enabled`] if
36    /// and only if a dependency is not platform-dependent. They can never return
37    /// [`EnabledTernary::Unknown`].
38    ///
39    /// This variant does not currently understand expressions that always evaluate to true
40    /// (tautologies), like `cfg(any(unix, not(unix)))` or `cfg(all())`. In the future, an SMT
41    /// solver would be able to handle such expressions.
42    Always,
43
44    /// The union of a set of individual platforms.
45    ///
46    /// Dependency queries performed against this variant will return
47    /// [`EnabledTernary::Enabled`] if and only if a dependency is enabled on at
48    /// least one platform. They may also return [`EnabledTernary::Unknown`] if
49    /// the dependency isn't definitely enabled on any platform, but the status
50    /// is unknown on at least one platform (due to target features being
51    /// unknown).
52    ///
53    /// If the list is empty, every query against it returns
54    /// [`EnabledTernary::Disabled`], even for dependencies that are not
55    /// platform-dependent.
56    ///
57    /// Queries against this variant obey the following laws, where `|` is the
58    /// K3 OR on [`EnabledTernary`]:
59    ///
60    /// * The order of platforms doesn't matter, and duplicates don't change
61    ///   the result.
62    /// * `Platforms(a ++ b)` produces the same result as `Platforms(a) |
63    ///   Platforms(b)`.
64    /// * For platform-dependent statuses, `Platforms([p])` produces the same
65    ///   result as [`PlatformEval::eval`](crate::platform::PlatformEval::eval)
66    ///   against `p`.
67    Platforms(Vec<Arc<Platform>>),
68
69    /// The union of all platforms.
70    ///
71    /// Dependency queries performed against this variant will return [`EnabledTernary::Enabled`] if
72    /// a dependency is enabled on any platform.
73    ///
74    /// This variant does not currently understand expressions that always evaluate to false
75    /// (contradictions), like `cfg(all(unix, not(unix)))` or `cfg(any())`. In the future, an SMT
76    /// solver would be able to handle such expressions.
77    Any,
78}
79
80impl PlatformSpec {
81    /// Returns a `PlatformSpec` corresponding to the target platform, as
82    /// determined at build time.
83    ///
84    /// Returns an error if the build target was unknown to the version of
85    /// `target-spec` in use.
86    pub fn build_target() -> Result<Self, TargetSpecError> {
87        Ok(PlatformSpec::from(Platform::build_target()?))
88    }
89
90    /// Returns a `PlatformSpec` that matches any of the given platforms.
91    ///
92    /// An empty iterator produces `Platforms([])`, in which case no
93    /// dependencies are enabled. Callers that build the list by filtering a
94    /// larger set should be careful about this case.
95    pub fn platforms<I, P>(platforms: I) -> Self
96    where
97        I: IntoIterator<Item = P>,
98        P: Into<Arc<Platform>>,
99    {
100        PlatformSpec::Platforms(
101            platforms
102                .into_iter()
103                .map(|platform| platform.into())
104                .collect(),
105        )
106    }
107}
108
109impl<T: Into<Arc<Platform>>> From<T> for PlatformSpec {
110    #[inline]
111    fn from(platform: T) -> Self {
112        PlatformSpec::Platforms(vec![platform.into()])
113    }
114}
guppy/platform/platform_spec.rs

guppy/platform/
platform_spec.rs
