Feedback on `cargo-info` to prepare it for merging

[hi-rustin]

Reminder

I am working on merging the cargo-info subcommand into Cargo. There are a few points that need to be addressed before merging. I would like to get feedback on these points. You can find the key points of concern at the end of this post.

Background

This adds a new subcommand to Cargo, cargo info. This subcommand would allow users to get information about a crate from the command line, without having to go to the web.

The main motivation for this is to make it easier to get information about a crate from the command line. Currently, the way to get information about a crate is to go to the web and look it up on crates.io or find the crate's source code and look at the Cargo.toml file. This is not very convenient, especially not all information is displayed on the crates.io page. This command also has been requested by the community for a long time. You can find more discussion about this in cargo#948.

Another motivation is to make the workflow of finding and evaluating crates more efficient. In the current workflow, users can search for crates using cargo search, but then they have to go to the web to get more information about the crate. This is not very efficient, especially if the user is just trying to get a quick overview of the crate. This would allow users to quickly get information about a crate without having to leave the terminal.

Example usage:

$ cargo info clap
    Updating crates.io index
clap #argument #cli #arg #parser #parse
A simple to use, efficient, and full-featured Command Line Argument Parser
version: 4.4.18
license: MIT OR Apache-2.0
rust-version: 1.70.0
documentation: https://docs.rs/clap/4.4.18
repository: https://github.com/clap-rs/clap
features:
  default         = [std, color, help, usage, error-context, suggestions]
  std             = [clap_builder/std]
  color           = [clap_builder/color]
  help            = [clap_builder/help]
  usage           = [clap_builder/usage]
  error-context   = [clap_builder/error-context]
  suggestions     = [clap_builder/suggestions]
  cargo           = [clap_builder/cargo]
  debug           = [clap_builder/debug, clap_derive?/debug]
  deprecated      = [clap_builder/deprecated, clap_derive?/deprecated]
  derive          = [dep:clap_derive]
  env             = [clap_builder/env]
  string          = [clap_builder/string]
  unicode         = [clap_builder/unicode]
  unstable-doc    = [clap_builder/unstable-doc, derive]
  unstable-styles = [clap_builder/unstable-styles]
  unstable-v5     = [clap_builder/unstable-v5, clap_derive?/unstable-v5, deprecated]
  wrap_help       = [clap_builder/wrap_help]
dependencies:
  clap_builder@=4.4.18
  clap_derive@=4.4.7
owners:
  kbknapp (Kevin K.)
  github:rust-cli:maintainers (Maintainers)
  github:clap-rs:admins (Admins)

Detailed design

Content	Explanation	Why
clap	Name	The basic information.
#argument #cli #arg #parser #parse	Keywords	It's more like a category, which you can use to search for relevant alternatives.
A simple to use, efficient, and full-featured Command Line Argument Parser	Description	The basic information.
version: 4.4.18	Version	The basic information.
license: MIT OR Apache-2.0	License	When choosing a crate, it is crucial to consider the license.
rust-version: 1.70.0	MSRV	When choosing a crate, it is crucial to make sure it can work with your MSRV.
documentation: https://docs.rs/clap/4.4.18	Documentation Link	Use these links can find more docs and information.
repository: https://github.com/clap-rs/clap	Repo Link	Use these links can find more docs and information.
features:	Default Features And Other Features	It helps for enabling features.
dependencies:	All dependencies	It indicates what it depends on.
owners:	Owners	It indicates who maintains the crate.

Some important notes

Downloading the crate from any Cargo compatible registry

The cargo info command will download the crate from any Cargo compatible registry. It will then extract the information from the Cargo.toml file and display it in the terminal.

If the crate is already in the local cache, it will not download the crate again. It will get the information from the local cache.

Pick the correct version from the workspace

When executed in a workspace directory, the cargo info command chooses the version that the workspace is currently using.

If there's a lock file available, the version from this file will be used. In the absence of a lock file, the command attempts to select a version that is compatible with the Minimum Supported Rust Version (MSRV). And the lock file will be generated automatically.

The following hierarchy is used to determine the MSRV:

• First, the MSRV of the parent directory package is checked, if it exists.
• If the parent directory package does not specify an MSRV, the minimal MSRV of the workspace is checked.
• If neither the workspace nor the parent directory package specify an MSRV, the version of the current Rust compiler (rustc --version) is used.

Prior art

NPM

npm has a similar command called npm info. For example:

$ npm info lodash

[email protected] | MIT | deps: none | versions: 114
Lodash modular utilities.
https://lodash.com/

keywords: modules, stdlib, util

dist
.tarball: https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz
.shasum: 679591c564c3bffaae8454cf0b3df370c3d6911c
.integrity: sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==
.unpackedSize: 1.4 MB

maintainers:
- mathias <[email protected]>
- jdalton <[email protected]>
- bnjmnt4n <[email protected]>

dist-tags:
latest: 4.17.21

published over a year ago by bnjmnt4n <[email protected]>

Poetry

Poetry has a similar command called poetry show.

For example:

$ poetry show pendulum

name        : pendulum
version     : 1.4.2
description : Python datetimes made easy

dependencies
 - python-dateutil >=2.6.1
 - tzlocal >=1.4
 - pytzdata >=2017.2.2

required by
 - calendar >=1.4.0

Known Points of Concern

1. Report crates metrics? cargo-information#20

   Proposal:

   • recent download count (popularity)
   • last updated (give a feel for how active development is)
   • Only for crates.io.

2. What dependency fields might be relevant to indicate? cargo-information#23

   Proposal:

   • From @epage: Dependencies are mostly an implementation detail (except public) but people sometimes care, so I figure that holding off on private dependencies to --verbose might buy us more space.
   • From @hi-rustin: How about we show all the dependencies and only show the dev-dependencies and build-dependencies for a --verbose. I guess checking its dependencies before you use it in your project would always be considered.

3. How should we render features? cargo-information#26

   Proposal: Currently, it's a simple list of features and their dependencies. We could consider a tree view:

   features:
     parent1
       child1
     parent2
       child1*
   

4. What version should we default to within a workspace? What if it isn't the direct dependency but is a transitive dependency? cargo-information#29

[fbstj]

this may be redundant or already asked but:

1. what happens if you run cargo info bare inside a crate folder?

2. what happens if you run cargo info $crate inside a workspace that includes the $crate source

[hi-rustin]

Here are some detailed examples:

Inspect a crate from crates.io outside of the workspace

Users can utilize the cargo info command to retrieve details in any directory. This command extracts information from crates.io and presents it in the terminal.

For example, let's run the cargo info command for the home crate.

$ cargo info home
    Updating crates.io index
home
Shared definitions of home directories.
version: 0.5.9
license: MIT OR Apache-2.0
rust-version: 1.70.0
documentation: https://docs.rs/home
repository: https://github.com/rust-lang/cargo
dependencies:
  [email protected]
owners:
  alexcrichton (Alex Crichton)
  brson (Brian Anderson)
  LucioFranco (Lucio Franco)
  ehuss (Eric Huss)
  kinnison (Daniel Silverstone)
  rust-lang-owner

It will display the name, description, version, license, rust version, documentation, repository, and dependencies of the crate. It will also display the owners of the crate if available.

Inspect a crate from crates.io inside of the workspace

In a workspace directory, the cargo info command can also be used to gather details. While it retrieves information from crates.io for display in the terminal, it specifically selects the version used in the workspace.

Let's run the same command in the local rustup repository. Rustup uses the home crate as a dependency.

$ cargo info home
    Updating crates.io index
home
Shared definitions of home directories.
version: 0.5.9
license: MIT OR Apache-2.0
rust-version: 1.70.0
documentation: https://docs.rs/home
repository: https://github.com/rust-lang/cargo
dependencies:
  [email protected]
owners:
  alexcrichton (Alex Crichton)
  brson (Brian Anderson)
  LucioFranco (Lucio Franco)
  ehuss (Eric Huss)
  kinnison (Daniel Silverstone)
  rust-lang-owner
note: to see how you depend on home, run `cargo tree --invert --package [email protected]`

As you can see, it displays the same information as the previous example, but it also displays a note to see how you depend on the crate.

Inspect a local crate

To obtain information about a local crate, users can execute the cargo info command. This command will showcase details from the local Cargo.toml file.

Let's run the same command the local cargo repository. It manages the home crate.

$ cargo info home
home
Shared definitions of home directories.
version: 0.5.11 (from ./crates/home)
license: MIT OR Apache-2.0
rust-version: 1.73
documentation: https://docs.rs/home
homepage: https://github.com/rust-lang/cargo
repository: https://github.com/rust-lang/cargo
dependencies:
  [email protected]

As you can see, it inspects the local crate and displays the information from the Cargo.toml file. Because we get the information from the Cargo.toml file, it doesn't display the owners of the crate.

Inspect a specific version of a crate

cargo info supports inspecting a specific version of a crate. It uses the same package ID specification as cargo install and other Cargo commands. You can find more information about the package ID specification in the Cargo documentation.

Let's run the cargo info command for the home crate with the version 0.5.9.

$ cargo info [email protected]
    Updating crates.io index
home
Shared definitions of home directories.
version: 0.5.9
license: MIT OR Apache-2.0
rust-version: 1.70.0
documentation: https://docs.rs/home
repository: https://github.com/rust-lang/cargo
dependencies:
  [email protected]
owners:
  alexcrichton (Alex Crichton)
  brson (Brian Anderson)
  LucioFranco (Lucio Franco)
  ehuss (Eric Huss)
  kinnison (Daniel Silverstone)
  rust-lang-owner

[epage]

cargo info when inside a crate folder to auto-select that crate could be an interesting extension.

[hi-rustin]

1. We don't allow it now. But it seems we can pick the crate directly.
2. You can refer to Inspect a local crate. It will read the crate info from the local manifest.

[hi-rustin]

I guess we need to pick the default member here right? What if we have multiple default members? Or should we restrict it only to a specific crate directory?

[epage]

Let's restrict to the parent crate and error if there isn't one.

[jrose]

Given the differing behavior inside vs outside a workspace (and presumably with vs without a Cargo.lock), maybe it makes sense to say how the version was chosen? “locked version”, “latest compatible version”, “latest version”, “explicitly-specified version”

[danjl1100]

@hi-rustin

In the absence of a lock file, the command attempts to select a version that is compatible with the Minimum Supported Rust Version (MSRV). And the lock file will be generated automatically.

(emphasis added)

It stuck me as unexpected that an info-gathering command would write to the lock file. Is this behavior intended to give a consistent experience for the expected workflow? (cargo info, then cargo add)

Bottom line, would the crate looked up be added to the cargo.lock file? E.g. if you look up a few crates and settle on picking one, do the rest remain locked?

[Vorpal]

@hi-rustin

Currently, the way to get information about a crate is to go to the web and look it up on crates.io

I would argue that most people I know use lib.rs instead because it is so much better. Especially the search. And the page prominently lists things I actually want to know right at the top: what dependencies does it have (and which ones are tied to features or platform specific), when was the last release, what number of reverse dependencies does it have.

Now I see you have some of that in cargo info, great! But number of reverse dependencies, number of downloads and date of most recent release(s) (all important proxy variables for quality and maintenance status) seem to be missing. Without those I'll keep using lib.rs

EDIT: In general I would recommend that the crates.io team and cargo Info developers (or anyone making a tool like this for any ecosystem really) take inspiration from what info lib.rs presents about crates. Forget about the drama about the search, that is not relevant for what I'm discussing here. The info pages on crates are excellent: information dense yet readable with a lot of useful information for evaluating taking on a new dependency.

It also highlights things like if a crate is no-std, needs nightly, etc. Very useful!

If I'm on mobile it has info like number of downloads right at the top, while crates.io has that at the very bottom. So on crates.io I end going to the bottom first, then back to the top.

[cuviper]

For links, I would like to see the actual crates.io link so I can go browse it myself.

I have also thought that the docs.rs/.../source/ link would be handy, both from cargo info and from the crates.io page. The repo link is well and good for development purposes, but it's not always easy to find what exactly corresponds to the published release, and docs.rs has that.

[hi-rustin]

If you run the command within a workspace, it will generate the Cargo.lock file. Giving a pick reason sounds good to me. But I guess we can only show it with the --verbose flag.

[hi-rustin]

No, the queried package will not be directly locked in the current workspace. Its main purpose is if you run this command in a workspace and your worksapce depends on it. It will select the version in your worksapce. If it is not a dependency of your worksapce, it will get the highest version or the MSRV-compatible version of your workspace. But it won't add it directly as a dependency to the lock.

[hi-rustin]

@Vorpal

But number of reverse dependencies, number of downloads and date of most recent release(s) (all important proxy variables for quality and maintenance status) seem to be missing.

I mentioned this in the Known Points of Concern. You can see more about it at this issue.

[hi-rustin]

@Vorpal

It also highlights things like if a crate is no-std, needs nightly,

I think it is hard to get this information from the manifest. This command only can get information from the manifest. So I think it is difficult to display this information.

[hi-rustin]

Sounds good to me. We already add https://docs.rs/{name}/{version} if there is no documentation link in the metadata. It seems reasonable to show the crossposting link here.

[jtgeibel]

@hi-rustin we briefly discussed this proposal at the last crates.io team meeting, and since you weren't available last week I said I would follow up here. When I originally skimmed this thread I thought that listing the crate owners in the default cargo info output might slightly extend the API surface that cargo hits. However, now that I've had a chance to take a closer look I see that this is the same output already available via cargo owner --list, so no worries there.

I recall you brought this proposal up with the team around 2 months ago. Based on this comment it sounds like we discussed the /api/v1/crates/:crate_id/:version endpoint at that time, though I think you're actually hitting the /api/v1/crates/:crate_id endpoint for the following (which are not included in the version specific output):

• keywords
• license (actually provided by both endpoints)
• documentation URL
• repository URL

From a quick review, I think everything else (other than the owner info of course) is coming directly from the index. If I've missed anything, please let us know.

In summary, I don't think there are any concerns here, and I just want to make sure we're all on the same page about any additional API exposure to the official cargo client.

[hi-rustin]

@jtgeibel

though I think you're actually hitting the /api/v1/crates/:crate_id endpoint for the following (which are not included in the version specific output):

• keywords
• license (actually provided by both endpoints)
• documentation URL
• repository URL

Thanks for reaching out!

Oh, it hasn't accessed the API to get the information. It gets this information from the manifest(download it if not in the cache). cargo-info only gets owner information from crates.io API right now. But in the future, we will call /api/v1/crates/:crate_id/:version to get download and update(release) information.