Trait cargo::sources::source::Source

source ·
pub trait Source {
Show 18 methods // Required methods fn source_id(&self) -> SourceId; fn supports_checksums(&self) -> bool; fn requires_precise(&self) -> bool; fn query( &mut self, dep: &Dependency, kind: QueryKind, f: &mut dyn FnMut(Summary) ) -> Poll<CargoResult<()>>; fn invalidate_cache(&mut self); fn set_quiet(&mut self, quiet: bool); fn download(&mut self, package: PackageId) -> CargoResult<MaybePackage>; fn finish_download( &mut self, pkg_id: PackageId, contents: Vec<u8> ) -> CargoResult<Package>; fn fingerprint(&self, pkg: &Package) -> CargoResult<String>; fn describe(&self) -> String; fn add_to_yanked_whitelist(&mut self, pkgs: &[PackageId]); fn is_yanked(&mut self, _pkg: PackageId) -> Poll<CargoResult<bool>>; fn block_until_ready(&mut self) -> CargoResult<()>; // Provided methods fn replaced_source_id(&self) -> SourceId { ... } fn query_vec( &mut self, dep: &Dependency, kind: QueryKind ) -> Poll<CargoResult<Vec<Summary>>> { ... } fn download_now( self: Box<Self>, package: PackageId, config: &Config ) -> CargoResult<Package> where Self: Sized { ... } fn verify(&self, _pkg: PackageId) -> CargoResult<()> { ... } fn is_replaced(&self) -> bool { ... }
}
Expand description

An abstraction of different sources of Cargo packages.

The Source trait generalizes the API to interact with these providers. For example,

Normally, developers don’t need to implement their own Sources. Cargo provides several kinds of sources implementations that should cover almost all use cases. See crate::sources for implementations provided by Cargo.

Required Methods§

source

fn source_id(&self) -> SourceId

Returns the SourceId corresponding to this source.

source

fn supports_checksums(&self) -> bool

Returns whether or not this source will return Summary items with checksums listed.

source

fn requires_precise(&self) -> bool

Returns whether or not this source will return Summary items with the precise field in the SourceId listed.

source

fn query( &mut self, dep: &Dependency, kind: QueryKind, f: &mut dyn FnMut(Summary) ) -> Poll<CargoResult<()>>

Attempts to find the packages that match a dependency request.

Usually you should call Source::block_until_ready somewhere and wait until package information become available. Otherwise any query may return a Poll::Pending.

The f argument is expected to get called when any Summary becomes available.

source

fn invalidate_cache(&mut self)

Ensure that the source is fully up-to-date for the current session on the next query.

source

fn set_quiet(&mut self, quiet: bool)

If quiet, the source should not display any progress or status messages.

source

fn download(&mut self, package: PackageId) -> CargoResult<MaybePackage>

Starts the process to fetch a Package for the given PackageId.

If the source already has the package available on disk, then it should return immediately with MaybePackage::Ready with the Package. Otherwise it should return a MaybePackage::Download to indicate the URL to download the package (this is for remote registry sources only).

In the case where MaybePackage::Download is returned, then the package downloader will call Source::finish_download after the download has finished.

source

fn finish_download( &mut self, pkg_id: PackageId, contents: Vec<u8> ) -> CargoResult<Package>

Gives the source the downloaded .crate file.

When a source has returned MaybePackage::Download in the Source::download method, then this function will be called with the results of the download of the given URL. The source is responsible for saving to disk, and returning the appropriate Package.

source

fn fingerprint(&self, pkg: &Package) -> CargoResult<String>

Generates a unique string which represents the fingerprint of the current state of the source.

This fingerprint is used to determine the “freshness” of the source later on. It must be guaranteed that the fingerprint of a source is constant if and only if the output product will remain constant.

The pkg argument is the package which this fingerprint should only be interested in for when this source may contain multiple packages.

source

fn describe(&self) -> String

Describes this source in a human readable fashion, used for display in resolver error messages currently.

source

fn add_to_yanked_whitelist(&mut self, pkgs: &[PackageId])

Add a number of crates that should be whitelisted for showing up during queries, even if they are yanked. Currently only applies to registry sources.

source

fn is_yanked(&mut self, _pkg: PackageId) -> Poll<CargoResult<bool>>

Query if a package is yanked. Only registry sources can mark packages as yanked. This ignores the yanked whitelist.

source

fn block_until_ready(&mut self) -> CargoResult<()>

Block until all outstanding Poll::Pending requests are Poll::Ready.

After calling this function, the source should return Poll::Ready for any queries that previously returned Poll::Pending.

If no queries previously returned Poll::Pending, and Source::invalidate_cache was not called, this function should be a no-op.

Provided Methods§

source

fn replaced_source_id(&self) -> SourceId

Returns the replaced SourceId corresponding to this source.

source

fn query_vec( &mut self, dep: &Dependency, kind: QueryKind ) -> Poll<CargoResult<Vec<Summary>>>

Gathers the result from Source::query as a list of Summary items when they become available.

source

fn download_now( self: Box<Self>, package: PackageId, config: &Config ) -> CargoResult<Package>where Self: Sized,

Convenience method used to immediately fetch a Package for the given PackageId.

This may trigger a download if necessary. This should only be used when a single package is needed (as in the case for cargo install). Otherwise downloads should be batched together via PackageSet.

source

fn verify(&self, _pkg: PackageId) -> CargoResult<()>

If this source supports it, verifies the source of the package specified.

Note that the source may also have performed other checksum-based verification during the download step, but this is intended to be run just before a crate is compiled so it may perform more expensive checks which may not be cacheable.

source

fn is_replaced(&self) -> bool

Returns whether a source is being replaced by another here.

Implementations on Foreign Types§

source§

impl<'a, T: Source + ?Sized + 'a> Source for &'a mut T

A blanket implementation forwards all methods to Source.

source§

impl<'a, T: Source + ?Sized + 'a> Source for Box<T>

A blanket implementation forwards all methods to Source.

Implementors§

source§

impl<'cfg> Source for DirectorySource<'cfg>

source§

impl<'cfg> Source for GitSource<'cfg>

source§

impl<'cfg> Source for PathSource<'cfg>

source§

impl<'cfg> Source for RegistrySource<'cfg>

source§

impl<'cfg> Source for ReplacedSource<'cfg>