Struct cargo::core::registry::PackageRegistry

pub struct PackageRegistry<'cfg> { /* fields omitted */ }

This structure represents a registry of known packages. It internally contains a number of Box<Source> instances which are used to load a Package from.

The resolution phase of Cargo uses this to drive knowledge about new packages as well as querying for lists of new packages. It is here that sources are updated (e.g. network operations) and overrides are handled.

The general idea behind this registry is that it is centered around the SourceMap structure, contained within which is a mapping of a SourceId to a Source. Each Source in the map has been updated (using network operations if necessary) and is ready to be queried for packages.

Methods

impl<'cfg> PackageRegistry<'cfg>

pub fn new(config: &'cfg Config) -> CargoResult<PackageRegistry<'cfg>>

pub fn get(self, package_ids: &[PackageId]) -> CargoResult<PackageSet<'cfg>>

pub fn add_sources(
    &mut self,
    ids: impl IntoIterator<Item = SourceId>
) -> CargoResult<()>

pub fn add_preloaded(&mut self, source: Box<dyn Source + 'cfg>)

pub fn add_override(&mut self, source: Box<dyn Source + 'cfg>)

pub fn add_to_yanked_whitelist(&mut self, iter: impl Iterator<Item = PackageId>)

pub fn register_lock(&mut self, id: PackageId, deps: Vec<PackageId>)

pub fn patch(&mut self, url: &Url, deps: &[Dependency]) -> CargoResult<()>

Insert a [patch] section into this registry.

This method will insert a [patch] section for the url specified, with the given list of dependencies. The url specified is the URL of the source to patch (for example this is crates-io in the manifest). The deps is an array of all the entries in the [patch] section of the manifest.

Here the deps will be resolved to a precise version and stored internally for future calls to query below. It's expected that deps have had lock_to call already, if applicable. (e.g. if a lock file was already present).

Note that the patch list specified here will not be available to query until lock_patches is called below, which should be called once all patches have been added.

pub fn lock_patches(&mut self)

Lock all patch summaries added via patch, making them available to resolution via query.

This function will internally lock each summary added via patch above now that the full set of patch packages are known. This'll allow us to correctly resolve overridden dependencies between patches hopefully!

pub fn patches(&self) -> &HashMap<Url, Vec<Summary>>

pub fn lock(&self, summary: Summary) -> Summary

This function is used to transform a summary to another locked summary if possible. This is where the concept of a lockfile comes into play.

If a summary points at a package id which was previously locked, then we override the summary's id itself, as well as all dependencies, to be rewritten to the locked versions. This will transform the summary's source to a precise source (listed in the locked version) as well as transforming all of the dependencies from range requirements on imprecise sources to exact requirements on precise sources.

If a summary does not point at a package id which was previously locked, or if any dependencies were added and don't have a previously listed version, we still want to avoid updating as many dependencies as possible to keep the graph stable. In this case we map all of the summary's dependencies to be rewritten to a locked version wherever possible. If we're unable to map a dependency though, we just pass it on through.

Trait Implementations

impl<'cfg> Registry for PackageRegistry<'cfg>

fn query(
    &mut self,
    dep: &Dependency,
    f: &mut dyn FnMut(Summary),
    fuzzy: bool
) -> CargoResult<()>

Attempt to find the packages that match a dependency request.

fn describe_source(&self, id: SourceId) -> String

fn is_replaced(&self, id: SourceId) -> bool

fn query_vec(
    &mut self,
    dep: &Dependency,
    fuzzy: bool
) -> CargoResult<Vec<Summary>>