Struct guppy::graph::summaries::PackageSetSummary

pub struct PackageSetSummary {
    pub summary_ids: BTreeSet<SummaryId>,
    pub workspace_members: BTreeSet<String>,
    pub third_party: Vec<ThirdPartySummary>,
}

Available on crate feature summaries only.

A set of packages specified in a summary. Can be resolved into a PackageSet given a PackageGraph.

Requires the summaries feature to be enabled.

Examples

Parsing a summary from a TOML specification, as found in e.g. a config file.

// This is an example TOML config for a PackageSet resolved from this workspace.
static TOML_INPUT: &str = r#"
workspace-members = ["guppy", "target-spec"]
# The version field specifies a range, just like Cargo.
# Third-party specifications also include "git" and "path".
third-party = [
    { name = "serde", version = "*" },
    { name = "rayon", version = "1.5" },
]
"#;

let summary: PackageSetSummary = toml::from_str(TOML_INPUT).expect("input parsed correctly");

let graph = MetadataCommand::new().build_graph().expect("guppy graph constructed");
let package_set = summary
    .to_package_set(&graph, "resolving example TOML")
    .expect("all elements matched");
let package_names: HashSet<_> = package_set
    .packages(DependencyDirection::Forward)
    .map(|metadata| metadata.name())
    .collect();

let mut expected_names = HashSet::new();
expected_names.extend(["guppy", "target-spec", "serde", "rayon"]);
assert_eq!(package_names, expected_names, "package names matched");

Specifying an invalid package results in an error.

// This is an example TOML config that contains package names that are unknown to this
// workspace.
static UNKNOWN_TOML_INPUT: &str = r#"
# serde is a third-party dependency, so it won't be matched in workspace-members.
workspace-members = ["unknown-member", "serde"]
# guppy is a workspace dependency, so it won't be matched in workspace-members.
# serde is present but the version number doesn't match.
third-party = [
    { name = "guppy" },
    { name = "serde", version = "0.9" },
    { name = "unknown-third-party" },
]
"#;

let summary: PackageSetSummary = toml::from_str(UNKNOWN_TOML_INPUT).expect("input parsed correctly");

let graph = MetadataCommand::new().build_graph().expect("guppy graph constructed");
let err = summary
    .to_package_set(&graph, "resolving example TOML")
    .expect_err("some elements are unknown");

assert_eq!(
    format!("{}", err),
    r#"unknown elements: resolving example TOML
* unknown workspace names:
  - serde
  - unknown-member
* unknown third-party:
  - { name = "guppy", version = "*", source = crates.io }
  - { name = "serde", version = "^0.9", source = crates.io }
  - { name = "unknown-third-party", version = "*", source = crates.io }
"#
);

Fields

summary_ids: BTreeSet<SummaryId>

A set of summary identifiers. Typically used in generated summaries.

Does not require a PackageGraph as context.

workspace_members: BTreeSet<String>

Workspace packages, specified by names. Typically used in config files.

These require a PackageGraph as context.

third_party: Vec<ThirdPartySummary>

Non-workspace packages, including non-workspace path dependencies. Typically used in config files.

Requires a PackageGraph as context.

Implementations

impl PackageSetSummary

pub fn new(package_set: &PackageSet<'_>) -> Self

Constructs a PackageSetSummary from a PackageSet.

pub fn from_package_ids<'a>( graph: &PackageGraph, package_ids: impl IntoIterator<Item = &'a PackageId> ) -> Result<Self, Error>

Constructs a PackageSetSummary from an iterator of PackageIds.

pub fn is_empty(&self) -> bool

Returns true if this PackageSetSummary is empty.

pub fn to_package_set<'g>( &self, graph: &'g PackageGraph, error_message: impl Into<String> ) -> Result<PackageSet<'g>, Error>

Converts this PackageSetSummary to a PackageSet.

Returns an error if any of the elements weren’t matched.

pub fn to_package_set_registry<'g, 'a>( &'a self, graph: &'g PackageGraph, registry_name_to_url: impl FnMut(&str) -> Option<&'a str>, error_message: impl Into<String> ) -> Result<PackageSet<'g>, Error>

Converts this PackageSetSummary to a PackageSet, with the given source for registry names.

Returns an error if any of the elements weren’t matched.

This is a temporary workaround until Cargo issue #9052 is resolved.

Trait Implementations

impl Clone for PackageSetSummary

fn clone(&self) -> PackageSetSummary

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PackageSetSummary

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for PackageSetSummary

fn default() -> PackageSetSummary

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for PackageSetSummary

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for PackageSetSummary

fn eq(&self, other: &PackageSetSummary) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for PackageSetSummary

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for PackageSetSummary

impl StructuralPartialEq for PackageSetSummary