Skip to content

Commit 00c688c

Browse files
Eh2406Eh2406
authored
move solver mod comment to resolver (#319)
* move solver mod comment to resolver * Some nits * fix todos. removing the Version trait
1 parent 2335796 commit 00c688c

File tree

2 files changed

+73
-77
lines changed

2 files changed

+73
-77
lines changed

‎src/lib.rs

+18-17
Original file line numberDiff line numberDiff line change
@@ -8,23 +8,6 @@
88
//! we should try to provide a very human-readable and clear
99
//! explanation as to why that failed.
1010
//!
11-
//! # Package and Version traits
12-
//!
13-
//! All the code in this crate is manipulating packages and versions, and for this to work
14-
//! we defined a [Package] trait
15-
//! that is used as bounds on most of the exposed types and functions.
16-
//!
17-
//! Package identifiers needs to implement our [Package] trait,
18-
//! which is automatic if the type already implements
19-
//! [Clone] + [Eq] + [Hash] + [Debug] + [Display](std::fmt::Display).
20-
//! So things like [String] will work out of the box.
21-
//!
22-
//! TODO! This is all wrong. Need to talk about VS, not Version.
23-
//! Our Version trait requires
24-
//! [Clone] + [Ord] + [Debug] + [Display](std::fmt::Display).
25-
//! For convenience, this library provides [SemanticVersion]
26-
//! that implements semantic versioning rules.
27-
//!
2811
//! # Basic example
2912
//!
3013
//! Let's imagine that we are building a user interface
@@ -59,6 +42,24 @@
5942
//! let solution = resolve(&dependency_provider, "root", 1u32).unwrap();
6043
//! ```
6144
//!
45+
//! # Package and Version flexibility
46+
//!
47+
//! The [OfflineDependencyProvider] used in that example is generic over the way package names,
48+
//! version requirements, and version numbers are represented.
49+
//!
50+
//! The first bound is the type of package names. It can be anything that implements our [Package] trait.
51+
//! The [Package] trait is automatic if the type already implements
52+
//! [Clone] + [Eq] + [Hash] + [Debug] + [Display](std::fmt::Display).
53+
//! So things like [String] will work out of the box.
54+
//!
55+
//! The second bound is the type of package requirements. It can be anything that implements our [VersionSet] trait.
56+
//! This trait is used to figure out how version requirements are combined.
57+
//! If the normal [Ord]/[PartialEq] operations are all that is needed for requirements, our [Ranges] type will work.
58+
//!
59+
//! The chosen `VersionSet` in turn specifies what can be used for version numbers.
60+
//! This type needs to at least implement [Clone] + [Ord] + [Debug] + [Display](std::fmt::Display).
61+
//! For convenience, this library provides [SemanticVersion] that implements the basics of semantic versioning rules.
62+
//!
6263
//! # DependencyProvider trait
6364
//!
6465
//! In our previous example we used the

‎src/solver.rs

+55-60
Original file line numberDiff line numberDiff line change
@@ -1,64 +1,5 @@
11
// SPDX-License-Identifier: MPL-2.0
22

3-
//! PubGrub version solving algorithm.
4-
//!
5-
//! It consists in efficiently finding a set of packages and versions
6-
//! that satisfy all the constraints of a given project dependencies.
7-
//! In addition, when that is not possible,
8-
//! PubGrub tries to provide a very human-readable and clear
9-
//! explanation as to why that failed.
10-
//! Below is an example of explanation present in
11-
//! the introductory blog post about PubGrub
12-
//!
13-
//! ```txt
14-
//! Because dropdown >=2.0.0 depends on icons >=2.0.0 and
15-
//! root depends on icons <2.0.0, dropdown >=2.0.0 is forbidden.
16-
//!
17-
//! And because menu >=1.1.0 depends on dropdown >=2.0.0,
18-
//! menu >=1.1.0 is forbidden.
19-
//!
20-
//! And because menu <1.1.0 depends on dropdown >=1.0.0 <2.0.0
21-
//! which depends on intl <4.0.0, every version of menu
22-
//! requires intl <4.0.0.
23-
//!
24-
//! So, because root depends on both menu >=1.0.0 and intl >=5.0.0,
25-
//! version solving failed.
26-
//! ```
27-
//!
28-
//! The algorithm is generic and works for any type of dependency system
29-
//! as long as packages (P) and versions (V) implement
30-
//! the [Package] and Version traits.
31-
//! [Package] is strictly equivalent and automatically generated
32-
//! for any type that implement [Clone] + [Eq] + [Hash] + [Debug] + [Display].
33-
//!
34-
//! ## API
35-
//!
36-
//! ```
37-
//! # use std::convert::Infallible;
38-
//! # use pubgrub::{resolve, OfflineDependencyProvider, PubGrubError, Ranges};
39-
//! #
40-
//! # type NumVS = Ranges<u32>;
41-
//! #
42-
//! # fn try_main() -> Result<(), PubGrubError<OfflineDependencyProvider<&'static str, NumVS>>> {
43-
//! # let dependency_provider = OfflineDependencyProvider::<&str, NumVS>::new();
44-
//! # let package = "root";
45-
//! # let version = 1u32;
46-
//! let solution = resolve(&dependency_provider, package, version)?;
47-
//! # Ok(())
48-
//! # }
49-
//! # fn main() {
50-
//! # assert!(matches!(try_main(), Err(PubGrubError::NoSolution(_))));
51-
//! # }
52-
//! ```
53-
//!
54-
//! Where `dependency_provider` supplies the list of available packages and versions,
55-
//! as well as the dependencies of every available package
56-
//! by implementing the [DependencyProvider] trait.
57-
//! The call to [resolve] for a given package at a given version
58-
//! will compute the set of packages and versions needed
59-
//! to satisfy the dependencies of that package and version pair.
60-
//! If there is no solution, the reason will be provided as clear as possible.
61-
623
use std::collections::BTreeSet as Set;
634
use std::error::Error;
645
use std::fmt::{Debug, Display};
@@ -107,8 +48,62 @@ impl PackageResolutionStatistics {
10748
}
10849
}
10950

110-
/// Main function of the library.
11151
/// Finds a set of packages satisfying dependency bounds for a given package + version pair.
52+
///
53+
/// It consists in efficiently finding a set of packages and versions
54+
/// that satisfy all the constraints of a given project dependencies.
55+
/// In addition, when that is not possible,
56+
/// PubGrub tries to provide a very human-readable and clear
57+
/// explanation as to why that failed.
58+
/// Below is an example of explanation present in
59+
/// the introductory blog post about PubGrub
60+
/// (Although this crate is not yet capable of building formatting quite this nice.)
61+
///
62+
/// ```txt
63+
/// Because dropdown >=2.0.0 depends on icons >=2.0.0 and
64+
/// root depends on icons <2.0.0, dropdown >=2.0.0 is forbidden.
65+
///
66+
/// And because menu >=1.1.0 depends on dropdown >=2.0.0,
67+
/// menu >=1.1.0 is forbidden.
68+
///
69+
/// And because menu <1.1.0 depends on dropdown >=1.0.0 <2.0.0
70+
/// which depends on intl <4.0.0, every version of menu
71+
/// requires intl <4.0.0.
72+
///
73+
/// So, because root depends on both menu >=1.0.0 and intl >=5.0.0,
74+
/// version solving failed.
75+
/// ```
76+
///
77+
/// Is generic over an implementation of [DependencyProvider] which represents where the dependency constraints come from.
78+
/// The associated types on the DependencyProvider allow flexibility for the representation of
79+
/// package names, version requirements, version numbers, and other things.
80+
/// See its documentation for more details.
81+
/// For simple cases [OfflineDependencyProvider](crate::OfflineDependencyProvider) may be sufficient.
82+
///
83+
/// ## API
84+
///
85+
/// ```
86+
/// # use std::convert::Infallible;
87+
/// # use pubgrub::{resolve, OfflineDependencyProvider, PubGrubError, Ranges};
88+
/// #
89+
/// # type NumVS = Ranges<u32>;
90+
/// #
91+
/// # fn try_main() -> Result<(), PubGrubError<OfflineDependencyProvider<&'static str, NumVS>>> {
92+
/// # let dependency_provider = OfflineDependencyProvider::<&str, NumVS>::new();
93+
/// # let package = "root";
94+
/// # let version = 1u32;
95+
/// let solution = resolve(&dependency_provider, package, version)?;
96+
/// # Ok(())
97+
/// # }
98+
/// # fn main() {
99+
/// # assert!(matches!(try_main(), Err(PubGrubError::NoSolution(_))));
100+
/// # }
101+
/// ```
102+
///
103+
/// The call to [resolve] for a given package at a given version
104+
/// will compute the set of packages and versions needed
105+
/// to satisfy the dependencies of that package and version pair.
106+
/// If there is no solution, the reason will be provided as clear as possible.
112107
#[cold]
113108
pub fn resolve<DP: DependencyProvider>(
114109
dependency_provider: &DP,

0 commit comments

Comments
 (0)