Crate crates_index

source ·
Expand description

Library for retrieving and interacting with the crates.io index.

§Examples

§Getting information about a single crate

let index = crates_index::GitIndex::new_cargo_default()?;
let serde_crate = index.crate_("serde").expect("you should handle errors here");
println!("Serde is at v{}", serde_crate.highest_normal_version().unwrap().version());

§Iterating over all crates in the index

let index = crates_index::GitIndex::new_cargo_default()?;
for crate_ in index.crates() {
   let latest = crate_.most_recent_version();
   println!("crate name: {}", latest.name());
   println!("most recently released version: {}", latest.version());
}

// or faster:
use rayon::prelude::*;
index.crates_parallel().for_each(|crate_| {
    /* etc. */
});

§Getting most recently published or yanked crates

let index = crates_index::GitIndex::new_cargo_default()?;

for c in index.changes()?.take(20) {
    let c = c?;
    println!("{} has changed in the index commit {}", c.crate_name(), c.commit_hex());
}

§Auto-cloning and parallelism

When using any means of instantiating the GitIndex type, we will clone the default crates index (or the given one) if it no git repository is present at the destination path.

This operation is racy and opening the index concurrently can lead to errors as multiple threads may try to clone the index at the same time if it wasn’t there yet.

To prevent that, consider using synchronization primitives on application level that synchronize methods like GitIndex::new_cargo_default() and its siblings.

§Git Repository Performance

By default, gix is compiled with max-performance-safe, which maximizes support for compilation environments but which may be slower as it uses a pure-Rust Zlib implementation. To get best possible performance, use the git-index-performance feature toggle.

§Using rustls instead of openssl when using the git-https feature in applications

When using the git-https feature, a choice will be made for you that involves selecting the curl backend for making the https protocol available. As using a different backend isn’t additive, as cargo features should be, one will have to resort to the following.

  • Change the crates-index dependency to features = ["git-index", …(everything else *but* "git-https")]
  • Add the gix dependency with default-features = false and features = ["blocking-http-transport-reqwest-rust-tls"]. Consider renaming the crate to gix-for-configuration-only = { package = "gix", … } to make the intend clear.

Please note that this should only be done in application manifests, who have the final say over the protocol and backend choices.

§Feature Flags

  • git — Activate support for accessing git-powered cargo indices. These have been superseded by the sparse-index, see the sparse feature.

  • git-performance — Activate support for git-powered cargo indices, but configure the underlying gix crate to use higher-performance sub-crates at the expense of platform compatibility.

    If it compiles for you, this should be preferred over git.

  • git-https — Add support for https based URLs in git indices.

    Most will want this enabled unless they know to only have to access non-https URLs for their indices.

  • parallel — Allow some functions to receive rayon-powered siblings for higher performance.

  • sparse (enabled by default) — Add support for communicating with sparse indices.

Modules§

  • error
    Re-exports in case you want to inspect specific error details
  • git
  • sparse

Structs§

  • Crate
    A whole crate with all its versions
  • Dependency
    A single dependency of a specific crate version
  • GitIndexgit
    Wrapper around managing the crates.io-index git repository
  • IndexConfig
    Global configuration of an index, reflecting the contents of config.json.
  • Names
    An iterator over all possible permutations of hyphens (-) and underscores (_) of a crate name.
  • SparseIndex
    Wrapper around managing a sparse HTTP index, re-using Cargo’s local disk caches.
  • Version
    A single version of a crate (package) published to the index

Enums§

Functions§