Struct PackageResolver 

pub struct PackageResolver<'a> { /* private fields */ }

As implied by the name, this is the implementation of the dependency/package resolver.

The resolver is constructed for a specific root package, along with a reference to the current state of the package index. Once constructed, you then ask the resolver for the dependencies of the given package using PackageResolver::resolve. It is then up to the caller to take those package and version selections and do something with them, typically fetching the actual package content and using it for program execution or assembly of a new package.

Implementations

impl<'a> PackageResolver<'a>

Construction

pub fn for_package_in_workspace( package: &'a Package, workspace: &'a Workspace, index: &'a PackageIndex, ) -> Self

Create a PackageResolver for package in workspace, using index.

It is assumed that the caller has already:

1. Ensured that index has been seeded with package, along with other members of workspace, and all versions of all packages known to the system that may be referenced as dependencies, directly or transitively.
2. Verified that package is a member of workspace. While resolution can still succeed if that isn’t the case, it may cause unexpected conflicts or selections to occur due to the special prioritization given to workspace members.

pub fn for_package(package: &'a Package, index: &'a PackageIndex) -> Self

Create a PackageResolver for package, using index.

For packages that are members of a workspace, you should prefer Self::for_package_in_workspace.

It is assumed that the caller has already:

1. Ensured that index has been seeded with package, along with all versions of all packages known to the system that may be referenced as dependencies, directly or transitively.

impl<'a> PackageResolver<'a>

Dependency resolution

pub fn resolve( self, ) -> Result<SelectedDependencies<Self>, DependencyResolutionError>

pub fn resolve_for( &self, package: impl Into<PackageId>, version: SemVer, ) -> Result<SelectedDependencies<Self>, DependencyResolutionError>

Resolve dependencies for package with the given version.

If successful, this returns a map of PackageId to Version for all dependencies required by package, transitively.

If unsuccesssful, a DependencyResolutionError is returned that indicates why it failed.

Trait Implementations

impl<'a> DependencyProvider for PackageResolver<'a>

This provides the version selection/dependency resolution functionality for PackageIndex via pubgrub.

We provide a custom implementation, as our versioning scheme must handle a mix of requirements including both semantic versioning schemes as well as requirements on a specific package digest.

type P = PackageId

The type used to identify packages in the provider

type V = Version

The type used to represent package versions

type VS = VersionSet

The type used to represent version requirements.

NOTE: Requirements must be able to process versions of type V

type M = String

The error type used to communicate our own version selection issues, e.g.:

• 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.

Currently we’re using String here as a placeholder until we determine a more appropriate error type.

type Priority = PackagePriority

The type used to represent prioritize package versions during selection.

type Err = Infallible

The error type returned from all functions of this trait that return errors.

Returning this signals that resolution should fail with this error.

We’re using Infallible here currently, as we don’t produce any errors that need to be returned yet, this is likely to change in the near future.

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.

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.

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.