Crate cargo_lock

RustSec: cargo-lock crate

Self-contained serde-powered Cargo.lock parser/serializer with support for the V1/V2/V3/V4 formats, as well as optional dependency tree analysis features. Used by RustSec.

When the dependency-tree feature of this crate is enabled, it supports computing a directed graph of the dependency tree, modeled using the petgraph crate, along with support for printing dependency trees ala the cargo-tree crate.

Documentation

Minimum Supported Rust Version

Rust 1.70 or higher.

Minimum supported Rust version can be changed in the future, but it will be accompanied by a minor version bump.

SemVer Policy

• MSRV is considered exempt from SemVer as noted above
• The cargo lock CLI interface is not considered to have a stable interface and is also exempted from SemVer. We reserve the right to make substantial changes to it at any time (for now)
• The dependency-tree feature depends on the pre-1.0 petgraph crate. We reserve the right to update petgraph, however when we do it will be accompanied by a minor version bump.

Command Line Interface

This crate provides a cargo lock subcommand which can be installed with:

cargo install cargo-lock --features=cli

It supports the following subcommands:

• list: list packages in Cargo.lock
• translate: translate Cargo.lock files between the V1 and V2 formats
• tree: print a dependency tree from Cargo.lock alone

See the crate documentation for more detailed usage information.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

Usage

use cargo_lock::Lockfile;

let lockfile = Lockfile::load("tests/examples/Cargo.lock").unwrap();
println!("number of dependencies: {}", lockfile.packages.len());

Dependency tree API

When the dependency-tree feature of this crate is enabled, it supports computing a directed graph of the dependency tree expressed in the lockfile, modeled using the petgraph crate, along with support for printing dependency trees ala the cargo-tree crate, a CLI interface for which is provided by the cargo lock tree subcommand described above.

This same graph representation of a Cargo.lock file is programmatically available via this crate’s API.

Command Line Interface

This crate provides a cargo lock Cargo subcommand which can be installed by running the following:

$ cargo install cargo-lock --features cli

It supports the following subcommands:

list: summarize packages in Cargo.lock

The cargo lock list subcommand (which can be shortened to just cargo lock if you prefer) provides a short synopsis of the packages enumerated in Cargo.lock:

$ cargo lock
- autocfg 1.0.0
- cargo-lock 4.0.1
- fixedbitset 0.2.0
- gumdrop 0.8.0
- gumdrop_derive 0.8.0
- idna 0.2.0
- indexmap 1.3.2
- matches 0.1.8
[...]

Adding a -d (or --dependencies) flag will show transitive dependencies:

$ cargo lock -d
- autocfg 1.0.0
- cargo-lock 4.0.1
  - gumdrop 0.8.0
  - petgraph 0.5.1
  - semver 0.10.0
  - serde 1.0.116
  - toml 0.5.6
  - url 2.1.1
- fixedbitset 0.2.0
- gumdrop 0.8.0
  - gumdrop_derive 0.8.0
- gumdrop_derive 0.8.0
  - proc-macro2 1.0.21
  - quote 1.0.3
  - syn 1.0.40
- idna 0.2.0
  - matches 0.1.8
  - unicode-bidi 0.3.4
  - unicode-normalization 0.1.12
[...]

Adding a -s (or --source) flag will show source information for each package (when available):

- autocfg 1.0.0 (registry+https://github.com/rust-lang/crates.io-index)
- cargo-lock 4.0.1
- fixedbitset 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)
- gumdrop 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)
- gumdrop_derive 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)
- idna 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)
- indexmap 1.3.2 (registry+https://github.com/rust-lang/crates.io-index)
[...]

translate: convert Cargo.lock files between the V1 and V2 formats

The cargo lock translate subcommand can translate V1 Cargo.lock files to the V2 format and vice versa:

$ cargo lock translate

…will translate Cargo.lock to the V2 format. To translate a V2 Cargo.lock file back to the V1 format, use:

$ cargo lock translate -v1

tree: provide information for how a dependency is included

The cargo lock tree subcommand (similar to the cargo-tree command) can provide a visualization of the current dependency tree or how a particular dependency is being used in your project, by consulting Cargo.lock alone:

$ cargo lock tree
cargo-lock 4.0.1
├── url 2.1.1
│   ├── percent-encoding 2.1.0
│   ├── matches 0.1.8
│   └── idna 0.2.0
│       ├── unicode-normalization 0.1.12
│       │   └── smallvec 1.2.0
│       ├── unicode-bidi 0.3.4
│       │   └── matches 0.1.8
│       └── matches 0.1.8
├── toml 0.5.6
│   └── serde 1.0.116
│       └── serde_derive 1.0.116
[...]

$ cargo lock tree syn
syn 1.0.14
├── serde_derive 1.0.104
│   └── serde 1.0.104
│       ├── toml 0.5.6
│       │   └── cargo-lock 3.0.0
│       ├── semver 0.9.0
│       │   └── cargo-lock 3.0.0
│       └── cargo-lock 3.0.0
└── gumdrop_derive 0.7.0
   └── gumdrop 0.7.0
       └── cargo-lock 3.0.0

Re-exports

• pub use crate::dependency::Dependency;
• pub use crate::package::Checksum;
• pub use crate::package::Name;
• pub use crate::package::Package;
• pub use crate::package::SourceId;

Modules

• dependency
  Package dependencies
• package
  Rust packages enumerated in Cargo.lock

Structs

• Lockfile
  Parsed Cargo.lock file containing dependencies
• MetadataKey
  Keys for the [metadata] table
• MetadataValue
  Values in the [metadata] table
• Patch
  The [[patch]] section of Cargo.lock
• Version
  SemVer version as defined by https://semver.org.

Enums

• Error
  Error type.
• ResolveVersion
  Lockfile versions

Type Aliases

• Metadata
  Package metadata
• Result
  Result type with the cargo-lock crate’s Error type.