Trait DependencyProvider

pub trait DependencyProvider {
    type P: Package;
    type V: Debug + Display + Clone + Ord;
    type VS: VersionSet<V = Self::V>;
    type Priority: Ord + Clone;
    type M: Eq + Clone + Debug + Display;
    type Err: Error + 'static;

    // Required methods
    fn prioritize(
        &self,
        package: &Self::P,
        range: &Self::VS,
        package_conflicts_counts: &PackageResolutionStatistics,
    ) -> Self::Priority;
    fn choose_version(
        &self,
        package: &Self::P,
        range: &Self::VS,
    ) -> Result<Option<Self::V>, Self::Err>;
    fn get_dependencies(
        &self,
        package: &Self::P,
        version: &Self::V,
    ) -> Result<Dependencies<Self::P, Self::VS, Self::M>, Self::Err>;

    // Provided method
    fn should_cancel(&self) -> Result<(), Self::Err> { ... }
}

Trait that allows the algorithm to retrieve available packages and their dependencies. An implementor needs to be supplied to the resolve function.

Required Associated Types

type P: Package

How this provider stores the name of the packages.

type V: Debug + Display + Clone + Ord

How this provider stores the versions of the packages.

A common choice is SemanticVersion.

type VS: VersionSet<V = Self::V>

How this provider stores the version requirements for the packages. The requirements must be able to process the same kind of version as this dependency provider.

A common choice is Ranges.

type Priority: Ord + Clone

The type returned from prioritize. The resolver does not care what type this is as long as it can pick a largest one and clone it.

Reverse can be useful if you want to pick the package with the fewest versions that match the outstanding constraint.

type M: Eq + Clone + Debug + Display

Type for custom incompatibilities.

There are reasons in user code outside pubgrub that can cause packages or versions to be unavailable. Examples:

• The version would require building the package, but builds are disabled.
• The package is not available in the cache, but internet access has been disabled.
• The package uses a legacy format not supported anymore.

The intended use is to track them in an enum and assign them to this type. You can also assign String as placeholder.

type Err: Error + 'static

The kind of error returned from these methods.

Returning this signals that resolution should fail with this error.

Required Methods

fn prioritize( &self, package: &Self::P, range: &Self::VS, package_conflicts_counts: &PackageResolutionStatistics, ) -> Self::Priority

Determine the order in which versions are chosen for packages.

Decisions are always made for the highest priority package first. The order of decisions determines which solution is chosen and can drastically change the performances of the solver. If there is a conflict between two package versions, decisions will be backtracked until the lower priority package version is discarded preserving the higher priority package. Usually, you want to decide more certain packages (e.g. those with a single version constraint) and packages with more conflicts first.

The package_conflicts_counts argument provides access to some other heuristics that are production users have found useful. Although the exact meaning/efficacy of those arguments may change.

The function is called once for each new package and then cached until we detect a (potential) change to range, otherwise it is cached, assuming that the priority only depends on the arguments to this function.

If two packages have the same priority, PubGrub will bias toward a breadth first search.

fn choose_version( &self, package: &Self::P, range: &Self::VS, ) -> Result<Option<Self::V>, Self::Err>

Once the resolver has found the highest Priority package from all potential valid packages, it needs to know what version of that package to use. The most common pattern is to select the largest version that the range contains.

fn get_dependencies( &self, package: &Self::P, version: &Self::V, ) -> Result<Dependencies<Self::P, Self::VS, Self::M>, Self::Err>

Retrieves the package dependencies. Return Dependencies::Unavailable if its dependencies are unavailable.

Provided Methods

fn should_cancel(&self) -> Result<(), Self::Err>

This is called fairly regularly during the resolution, if it returns an Err then resolution will be terminated. This is helpful if you want to add some form of early termination like a timeout, or you want to add some form of user feedback if things are taking a while. If not provided the resolver will run as long as needed.

Implementors

impl<P: Package, VS: VersionSet> DependencyProvider for OfflineDependencyProvider<P, VS>

An implementation of DependencyProvider that contains all dependency information available in memory. Currently packages are picked with the fewest versions contained in the constraints first. But, that may change in new versions if better heuristics are found. Versions are picked with the newest versions first.

type P = P

type V = <VS as VersionSet>::V

type VS = VS

type M = String

type Err = Infallible

type Priority = (u32, Reverse<usize>)