guppy_summaries/lib.rs
1// Copyright (c) The cargo-guppy Contributors
2// SPDX-License-Identifier: MIT OR Apache-2.0
3
4//! Facilities to serialize, deserialize and compare build summaries.
5//!
6//! A *build summary* is a record of what packages and features are built on the target and host
7//! platforms. A summary file can be checked into a repository, kept up to date and compared in CI,
8//! and allow for tracking results of builds over time.
9//!
10//! `guppy-summaries` is designed to be small and independent of the main `guppy` crate.
11//!
12//! # Examples
13//!
14//! ```rust
15//! use guppy_summaries::{Summary, SummaryId, SummarySource, PackageStatus};
16//! use pretty_assertions::assert_eq;
17//! use semver::Version;
18//! use std::collections::BTreeSet;
19//! use toml::Value;
20//!
21//! // A summary is a TOML file that has this format:
22//! static SUMMARY: &str = r#"
23//! [[target-package]]
24//! name = "foo"
25//! version = "1.2.3"
26//! workspace-path = "foo"
27//! status = 'initial'
28//! features = ["feature-a", "feature-c"]
29//!
30//! [[host-package]]
31//! name = "proc-macro"
32//! version = "0.1.2"
33//! workspace-path = "proc-macros/macro"
34//! status = 'workspace'
35//! features = ["macro-expand"]
36//!
37//! [[host-package]]
38//! name = "bar"
39//! version = "0.4.5"
40//! crates-io = true
41//! status = 'direct'
42//! features = []
43//! "#;
44//!
45//! // The summary can be deserialized:
46//! let summary = Summary::parse(SUMMARY).expect("from_str succeeded");
47//!
48//! // ... and a package and its features can be looked up.
49//! let summary_id = SummaryId::new("foo", Version::new(1, 2, 3), SummarySource::workspace("foo"));
50//! let info = &summary.target_packages[&summary_id];
51//! assert_eq!(info.status, PackageStatus::Initial, "correct status");
52//! assert_eq!(
53//! info.features.iter().map(|feature| feature.as_str()).collect::<Vec<_>>(),
54//! ["feature-a", "feature-c"],
55//! "correct feature list"
56//! );
57//!
58//! // Another summary.
59//! static SUMMARY2: &str = r#"
60//! [[target-package]]
61//! name = "foo"
62//! version = "1.2.4"
63//! workspace-path = "new-location/foo"
64//! status = 'initial'
65//! features = ["feature-a", "feature-b"]
66//!
67//! [[target-package]]
68//! name = "once_cell"
69//! version = "1.4.0"
70//! source = "git+https://github.com/matklad/once_cell?tag=v1.4.0"
71//! status = 'transitive'
72//! features = ["std"]
73//!
74//! [[host-package]]
75//! name = "bar"
76//! version = "0.4.5"
77//! crates-io = true
78//! status = 'direct'
79//! features = []
80//! "#;
81//!
82//! let summary2 = Summary::parse(SUMMARY2).expect("from_str succeeded");
83//!
84//! // Diff summary and summary2.
85//! let diff = summary.diff(&summary2);
86//!
87//! // Pretty-print a report generated from the diff.
88//! let diff_str = format!("{}", diff.report());
89//! assert_eq!(
90//! r#"target packages:
91//! A once_cell 1.4.0 (transitive third-party, external 'git+https://github.com/matklad/once_cell?tag=v1.4.0')
92//! * features: std
93//! M foo 1.2.4 (initial, path 'new-location/foo')
94//! * version upgraded from 1.2.3
95//! * source changed from path 'foo'
96//! * added features: feature-b
97//! * removed features: feature-c
98//! * (unchanged features: feature-a)
99//! * (unchanged optional dependencies: [none])
100//!
101//! host packages:
102//! R proc-macro 0.1.2 (workspace, path 'proc-macros/macro')
103//! * (old features: macro-expand)
104//!
105//! "#,
106//! diff_str,
107//! );
108//! ```
109
110#![forbid(unsafe_code)]
111#![warn(missing_docs)]
112
113pub mod diff;
114// report::SummaryReport is exported through the diff module.
115mod report;
116mod summary;
117#[cfg(test)]
118mod unit_tests;
119
120pub use summary::*;