Struct krates::Builder

pub struct Builder { /* fields omitted */ }

A builder used to create a Krates graph, either by running a cargo metadata command, or using an already deserialized cargo_metadata::Metadata

Methods

impl Builder

pub fn new() -> Self

pub fn ignore_kind(&mut self, kind: DepKind, scope: Scope) -> &mut Self

Ignores a specific dependency kind in the given scope.

Builder::new().ignore_kind(DepKind::Build, Scope::NonWorkspace);

In the above example, let's say we depended on zstd. zstd depends on the cc crate (zstd -> zstd-safe -> zstd-sys -> cc) for building C code. By ignoring the build kind for non-workspace crates, the link from zstd-sys -> cc will be filtered out. If the same cc is not depended on by a crate in the workspace, cc will not end up in the final Krates graph.

Note that ignoring DepKind::Dev for Scope::NonWorkspace is meaningless as dev dependencies are not resolved by cargo for transitive dependencies.

pub fn include_workspace_crates<P, I>(&mut self, crates: I) -> &mut Self where
    P: AsRef<Path>,
    I: IntoIterator<Item = P>, 

By default, every workspace crate is treated as a root node and implicitly added to the graph if the graph is built from a workspace context and not a specific crate in the workspace.

By using this method, only the workspace crates whose Cargo.toml path matches one of the specified crates will be added as root notes, meaning that any workspace crate not in the list that doesn't have any dependendents on a workspace crate that does, will no longer appear in the graph.

If you specify only a single path, and that path is actually to a workspace's Cargo.toml, this will function exactly the same.

Builder::new().include_workspace_crates(&["path/to/some/crate"]);

pub fn include_targets<S: AsRef<str>>(
    &mut self,
    targets: impl IntoIterator<Item = (S, Vec<String>)>
) -> &mut Self

By default, cargo resolves all target specific dependencies. Optionally, you can use the --filter-platform option on cargo metadata to resolve only dependencies that match the specified target, but it can only do this for one platlform.

By using this method, you can specify one or more targets by their triple, as well as any target_features that you promise are enabled for that target to filter dependencies by. If any of the specified targets matches a target specific dependency, it will be included in the graph.

When specifying a target triple, only builtin targets of rustc (as of 1.40) can be used to evaluate cfg() expressions. If the triple is not recognized, it will only be evaluated against [target.<triple-or-json>.<|build-|dev->dependencies].

let targets = [
    // the big 3
    "x86_64-unknown-linux-gnu",
    "x86_64-pc-windows-msvc",
    "x86_64-apple-darwin",
    // and musl!
    "x86_64-unknown-linux-musl",
    // and wasm (with the fancy atomics feature!)
    "wasm32-unknown-unknown",
];

Builder::new().include_targets(targets.into_iter().map(|triple| {
    if triple.starts_with("wasm32") {
        (*triple, vec!["atomics".to_owned()])
    } else {
        (*triple, vec![])
    }
}));

pub fn build<N, E, F>(
    self,
    cmd: impl Into<MetadataCommand>,
    on_filter: F
) -> Result<Krates<N, E>, Error> where
    N: From<Package>,
    E: From<Edge>,
    F: OnFilter, 

Builds a Krates graph using metadata that be retrieved via the specified metadata command. If on_filter is specified, it will be called with each package that was filtered from the graph, if any.

This method will fail if the metadata command fails for some reason, or if the command specifies --no-deps which means there will be no resolution graph to build our graph from.

let mut mdc = krates::Cmd::new();
mdc.manifest_path("path/to/Cargo.toml");

if /*no_default_features*/ true {
    mdc.no_default_features();
}

if /*cfg.all_features*/ false {
    mdc.all_features();
}

mdc.features(
    ["cool-feature", "cooler-feature", "coolest-feature"]
        .iter()
        .map(|s| s.to_string()),
);

let mut builder = krates::Builder::new();

if /*cfg.ignore_build_dependencies*/ false {
    builder.ignore_kind(krates::DepKind::Build, krates::Scope::All);
}

if /*cfg.ignore_dev_dependencies*/ true {
    builder.ignore_kind(krates::DepKind::Dev, krates::Scope::All);
}

let graph: krates::Krates = builder.build(
    mdc,
    |filtered: Package| match filtered.source {
        Some(src) => {
            if src.is_crates_io() {
                println!("filtered {} {}", filtered.name, filtered.version);
            } else {
                println!("filtered {} {} {}", filtered.name, filtered.version, src);
            }
        }
        None => println!("filtered crate {} {}", filtered.name, filtered.version),
    },
).unwrap();

pub fn build_with_metadata<N, E, F>(
    self,
    md: Metadata,
    on_filter: F
) -> Result<Krates<N, E>, Error> where
    N: From<Package>,
    E: From<Edge>,
    F: OnFilter, 

Builds a Krates graph using the specified metadata. If on_filter is specified, it will be called with each package that was filtered from the graph, if any.

The metadata must have resolved dependencies for the graph to be built, so not having it is the only way this method will fail.

let contents = std::fs::read_to_string("metadata.json")
    .map_err(|e| format!("failed to load metadata file: {}", e)).unwrap();

let md: krates::cm::Metadata = serde_json::from_str(&contents)
    .map_err(|e| format!("failed to deserialize metadata: {}", e)).unwrap();

let krates: Krates = Builder::new().build_with_metadata(
    md,
    |pkg: Package| println!("filtered {}", pkg.id)
).unwrap();

println!("found {} unique crates", krates.len());

Trait Implementations

impl Default for Builder

fn default() -> Builder

Returns the "default value" for a type.