guppy/platform/mod.rs
1// Copyright (c) The cargo-guppy Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Support for dependencies that are only enabled on some platforms.
5//!
6//! Most of the time, dependencies are enabled across all platforms. For example, in this
7//! `Cargo.toml`:
8//!
9//! ```toml
10//! # once_cell 1.5 is enabled on all platforms.
11//! [dependencies]
12//! once_cell = "1.5"
13//! ```
14//!
15//! However, in some cases, dependencies may only be enabled on certain platforms.
16//!
17//! ```toml
18//! # This dependency is only enabled on Linux x86_64.
19//! [target.x86_64-unknown-linux-gnu.dependencies]
20//! inotify = "0.9.4"
21//!
22//! # This build dependency is enabled on Windows.
23//! [target.'cfg(windows)'.build-dependencies]
24//! winapi = "0.3.9"
25//! ```
26//!
27//! This module provides types that can represent platforms and evaluate expressions.
28//!
29//! # Representing platforms
30//!
31//! * [`Platform`] represents a single platform.
32//! * [`Triple`] is a [Rust target triple](https://doc.rust-lang.org/stable/rustc/platform-support.html).
33//! * [`PlatformSpec`] represents a set of platforms: any platform (the union
34//! of all possible platforms), all platforms (the intersection of all
35//! possible platforms), or the union of an explicit, possibly empty, list of
36//! platforms.
37//!
38//! # Evaluating platforms
39//!
40//! These structs are defined in the context of a [`PackageGraph`](crate::graph::PackageGraph), and
41//! are typically returned through [`PackageLink`](crate::graph::PackageLink) instances.
42//!
43//! * [`PlatformStatus`]: The status of a dependency or a feature which might be platform-dependent.
44//! * [`PlatformEval`]: A collection of platform specifications like `cfg(unix)`, to evaluate
45//! against a platform.
46//! * [`EnabledTernary`]: A three-valued logic representing the status of a dependency or feature
47//! on a given platform. Includes an additional status to represent situations like unknown
48//! [target features](https://rust-lang.github.io/rfcs/2045-target-feature.html).
49//!
50//! If the `summaries` feature is enabled, this module also supports reading and writing serializable
51//! summaries of platforms. These can be used both as configuration, and to serialize the results of a
52//! particular `guppy` evaluation.
53//!
54//! For more, about platform-specific dependencies, see [Platform specific
55//! dependencies](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies)
56//! in the Cargo reference.
57
58mod platform_eval;
59mod platform_spec;
60#[cfg(feature = "proptest1")]
61mod proptest_helpers;
62#[cfg(feature = "summaries")]
63mod summaries;
64
65pub use platform_eval::*;
66pub use platform_spec::*;
67#[cfg(feature = "summaries")]
68pub use summaries::*;
69// These are inlined -- generally, treat target_spec as a private dependency so expose these types
70// as part of guppy's API.
71pub use target_spec::{Platform, TargetFeatures, Triple};