From 3dd72fe2265f053f02046ca45dfca78b35bbad2c Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Thu, 1 Feb 2024 23:04:49 +0800 Subject: [PATCH 01/14] blog: cargo-information pre-RFC Signed-off-by: hi-rustin --- .../2024-02-01-pre-RFC-cargo-information.md | 151 ++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 _posts/2024-02-01-pre-RFC-cargo-information.md diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md new file mode 100644 index 0000000..04c63d0 --- /dev/null +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -0,0 +1,151 @@ +--- +title: 'pre-RFC: `cargo-info` for everyone' +layout: post + +categories: post +tags: +- Rust +- Cargo +- CLI +--- + +# Summary + +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. + +Example usage: + +```sh +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) +``` + +# Motivation + +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. + +[crates.io]: https://crates.io +[cargo#948]: https://github.com/rust-lang/cargo/issues/948 + +# Guide-level explanation + +## Inspect a crate from crates.io outside of the workspace + +Users can run `cargo info` command to get information in any directory. This command will fetch the information from the crates.io index and display it in the terminal. + +```sh +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: + windows-sys@0.52 +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 + +Users can run `cargo info` command to get information in a workspace directory. This command will fetch the information from the crates.io index and display it in the terminal. But it will pick 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. + +```sh +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: + windows-sys@0.52 +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 home@0.5.9` +``` + +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 + +Users can run `cargo info` command to get information about a local crate. This command will display the information from the local `Cargo.toml` file. + +Let's run the same command the local [cargo repository]. It manages the `home` crate. + +```sh +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: + windows-sys@0.52 +``` + +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. + +# Reference-level explanation + +# Prior art + +# Unresolved questions From 033a3a1a339cd76f28d3ffde6346717a850dcac1 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Fri, 2 Feb 2024 21:41:08 +0800 Subject: [PATCH 02/14] refactor: rephrase Signed-off-by: hi-rustin --- _posts/2024-02-01-pre-RFC-cargo-information.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 04c63d0..14b3725 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -67,7 +67,9 @@ Another motivation is to make the workflow of finding and evaluating crates more ## Inspect a crate from crates.io outside of the workspace -Users can run `cargo info` command to get information in any directory. This command will fetch the information from the crates.io index and display it in the terminal. +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. ```sh cargo info home @@ -94,7 +96,7 @@ It will display the name, description, version, license, rust version, documenta ## Inspect a crate from crates.io inside of the workspace -Users can run `cargo info` command to get information in a workspace directory. This command will fetch the information from the crates.io index and display it in the terminal. But it will pick the version used in 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. @@ -122,9 +124,11 @@ note: to see how you depend on home, run `cargo tree --invert --package home@0.5 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. +[rustup repository]: https://github.com/rust-lang/rustup + ## Inspect a local crate -Users can run `cargo info` command to get information about a local crate. This command will display the information from the local `Cargo.toml` file. +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. @@ -144,6 +148,8 @@ dependencies: 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. +[cargo repository]: https://github.com/rust-lang/cargo + # Reference-level explanation # Prior art From 2c82bc8396d4a95bca22f6cfcc0a638d71e6da2f Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Fri, 2 Feb 2024 22:19:45 +0800 Subject: [PATCH 03/14] blog: add prior art Signed-off-by: hi-rustin --- .../2024-02-01-pre-RFC-cargo-information.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 14b3725..f695f80 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -150,8 +150,109 @@ As you can see, it inspects the local crate and displays the information from th [cargo repository]: https://github.com/rust-lang/cargo +## 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`. + +```sh +cargo info home@0.5.9 + 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: + windows-sys@0.52 +owners: + alexcrichton (Alex Crichton) + brson (Brian Anderson) + LucioFranco (Lucio Franco) + ehuss (Eric Huss) + kinnison (Daniel Silverstone) + rust-lang-owner +``` + +[Cargo documentation]: https://doc.rust-lang.org/cargo/reference/pkgid-spec.html + # Reference-level explanation +## 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`. This command allows users to get information about a package from the command line. + +For example: + +```sh +npm info lodash + +lodash@4.17.21 | 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 +- jdalton +- bnjmnt4n + +dist-tags: +latest: 4.17.21 + +published over a year ago by bnjmnt4n +``` + +## Poetry + +Poetry has a similar command called `poetry show`. This command allows users to get information about a package from the command line. + +For example: + +```sh +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 +``` + # Unresolved questions From a0cfb9326aac3fa6e50543d8f6e258d4bf0c6f43 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Fri, 2 Feb 2024 22:23:31 +0800 Subject: [PATCH 04/14] blog: shorter Signed-off-by: hi-rustin --- _posts/2024-02-01-pre-RFC-cargo-information.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index f695f80..89d07c1 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -203,8 +203,7 @@ The following hierarchy is used to determine the MSRV: ## NPM -npm has a similar command called `npm info`. This command allows users to get information about a package from the command line. - +npm has a similar command called `npm info`. For example: ```sh @@ -235,7 +234,7 @@ published over a year ago by bnjmnt4n ## Poetry -Poetry has a similar command called `poetry show`. This command allows users to get information about a package from the command line. +Poetry has a similar command called `poetry show`. For example: From e92859721fd591fa53ab84a8bd4f04abfbefcae5 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Mon, 5 Feb 2024 20:28:03 +0800 Subject: [PATCH 05/14] chore: add links Signed-off-by: hi-rustin --- _posts/2024-02-01-pre-RFC-cargo-information.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 89d07c1..371a813 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -203,7 +203,7 @@ The following hierarchy is used to determine the MSRV: ## NPM -npm has a similar command called `npm info`. +[npm] has a similar command called `npm info`. For example: ```sh @@ -232,9 +232,11 @@ latest: 4.17.21 published over a year ago by bnjmnt4n ``` +[npm]: https://www.npmjs.com/ + ## Poetry -Poetry has a similar command called `poetry show`. +[Poetry] has a similar command called `poetry show`. For example: @@ -254,4 +256,6 @@ required by - calendar >=1.4.0 ``` +[Poetry]: https://python-poetry.org/ + # Unresolved questions From 2e9e8c49525dd482a25bd3ba3eb4c9d25eec9977 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Mon, 5 Feb 2024 21:07:35 +0800 Subject: [PATCH 06/14] docs: add detailed design Signed-off-by: hi-rustin --- _posts/2024-02-01-pre-RFC-cargo-information.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 371a813..552ffe7 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -1,5 +1,5 @@ --- -title: 'pre-RFC: `cargo-info` for everyone' +title: 'pre-RFC: cargo-info for everyone' layout: post categories: post @@ -53,6 +53,22 @@ owners: 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 package, it is crucial to consider the license. | +| rust-version: 1.70.0 | MSRV | When choosing a package, it is crucial to make sure it can work with your MSRV. | +| documentation: | Documentation Link | Use these links can find more docs and information. | +| repository: | 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 package. | + # Motivation 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. From 855dfda337b93b351a7b2ed2cbd9e740e39f189c Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Mon, 5 Feb 2024 21:32:52 +0800 Subject: [PATCH 07/14] docs: add unresolved questions Signed-off-by: hi-rustin --- .../2024-02-01-pre-RFC-cargo-information.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 552ffe7..2201b70 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -275,3 +275,29 @@ required by [Poetry]: https://python-poetry.org/ # Unresolved questions + +1. Report crates metrics? + + 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? + + 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. + +3. How should we render features? + + Proposal: Currently, it's a simple list of features and their dependencies. We could consider a tree view: + + ```console + 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? From 80a82e9684909d44d84d1158e81792e417119662 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Mon, 5 Feb 2024 21:37:45 +0800 Subject: [PATCH 08/14] docs: add more proposals Signed-off-by: hi-rustin --- _posts/2024-02-01-pre-RFC-cargo-information.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 2201b70..70461c9 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -286,7 +286,10 @@ required by 2. What dependency fields might be relevant to indicate? - 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. + 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? From 50986fae6161a22e9ddb9cb21bef649365904ef5 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Mon, 5 Feb 2024 21:45:10 +0800 Subject: [PATCH 09/14] docs: add links Signed-off-by: hi-rustin --- _posts/2024-02-01-pre-RFC-cargo-information.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 70461c9..d436517 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -276,7 +276,7 @@ required by # Unresolved questions -1. Report crates metrics? +1. Report crates metrics? [cargo-information#20] Proposal: @@ -284,14 +284,14 @@ required by - last updated (give a feel for how active development is) - Only for crates.io. -2. What dependency fields might be relevant to indicate? +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? +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: @@ -303,4 +303,9 @@ required by child1* ``` -4. What version should we default to within a workspace? What if it isn't the direct dependency but is a transitive dependency? +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] + +[cargo-information#20]: https://github.com/hi-rustin/cargo-information/issues/20 +[cargo-information#23]: https://github.com/hi-rustin/cargo-information/issues/23 +[cargo-information#26]: https://github.com/hi-rustin/cargo-information/issues/26 +[cargo-information#29]: https://github.com/hi-rustin/cargo-information/issues/29 From 62f1b6794f04b1bf0ad6738cf5465bf486f30b2f Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Mon, 5 Feb 2024 21:47:30 +0800 Subject: [PATCH 10/14] fix: use `crate` Signed-off-by: hi-rustin --- _posts/2024-02-01-pre-RFC-cargo-information.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index d436517..40cce03 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -61,13 +61,13 @@ owners: | #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 package, it is crucial to consider the license. | -| rust-version: 1.70.0 | MSRV | When choosing a package, it is crucial to make sure it can work with your MSRV. | +| 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: | Documentation Link | Use these links can find more docs and information. | | repository: | 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 package. | +| owners: | Owners | It indicates who maintains the crate. | # Motivation From 96b8fac84225e8a4b7ed4e88526659d1f8f4ddd4 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Mon, 5 Feb 2024 09:03:55 -0600 Subject: [PATCH 11/14] fix: Use console code blocks --- .../2024-02-01-pre-RFC-cargo-information.md | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-pre-RFC-cargo-information.md index 40cce03..4462be1 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-pre-RFC-cargo-information.md @@ -15,8 +15,8 @@ This adds a new subcommand to Cargo, `cargo info`. This subcommand would allow u Example usage: -```sh -cargo info clap +```console +$ 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 @@ -87,8 +87,8 @@ Users can utilize the `cargo` info command to retrieve details in any directory. For example, let's run the `cargo info` command for the `home` crate. -```sh -cargo info home +```console +$ cargo info home Updating crates.io index home Shared definitions of home directories. @@ -116,8 +116,8 @@ In a workspace directory, the `cargo info` command can also be used to gather de Let's run the same command in the local [rustup repository]. Rustup uses the `home` crate as a dependency. -```sh -cargo info home +```console +$ cargo info home Updating crates.io index home Shared definitions of home directories. @@ -148,8 +148,8 @@ To obtain information about a local crate, users can execute the `cargo info` co Let's run the same command the local [cargo repository]. It manages the `home` crate. -```sh -cargo info home +```console +$ cargo info home home Shared definitions of home directories. version: 0.5.11 (from ./crates/home) @@ -172,8 +172,8 @@ As you can see, it inspects the local crate and displays the information from th Let's run the `cargo info` command for the `home` crate with the version `0.5.9`. -```sh -cargo info home@0.5.9 +```console +$ cargo info home@0.5.9 Updating crates.io index home Shared definitions of home directories. @@ -222,8 +222,8 @@ The following hierarchy is used to determine the MSRV: [npm] has a similar command called `npm info`. For example: -```sh -npm info lodash +```console +$ npm info lodash lodash@4.17.21 | MIT | deps: none | versions: 114 Lodash modular utilities. @@ -256,8 +256,8 @@ published over a year ago by bnjmnt4n For example: -```sh -poetry show pendulum +```console +$ poetry show pendulum name : pendulum version : 1.4.2 From 65870967afc2e705c35eb822b6685a674a0fdcb2 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Sun, 18 Feb 2024 22:28:06 +0800 Subject: [PATCH 12/14] blog: change title Signed-off-by: hi-rustin --- ...argo-information.md => 2024-02-01-feedback-on-cargo-info.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename _posts/{2024-02-01-pre-RFC-cargo-information.md => 2024-02-01-feedback-on-cargo-info.md} (99%) diff --git a/_posts/2024-02-01-pre-RFC-cargo-information.md b/_posts/2024-02-01-feedback-on-cargo-info.md similarity index 99% rename from _posts/2024-02-01-pre-RFC-cargo-information.md rename to _posts/2024-02-01-feedback-on-cargo-info.md index 4462be1..6712296 100644 --- a/_posts/2024-02-01-pre-RFC-cargo-information.md +++ b/_posts/2024-02-01-feedback-on-cargo-info.md @@ -1,5 +1,5 @@ --- -title: 'pre-RFC: cargo-info for everyone' +title: 'Feedback on `cargo-info` to prepare it for merging' layout: post categories: post From defc8412cb006d6cccbae62996a2f7c7f9d72686 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Tue, 20 Feb 2024 20:54:56 +0800 Subject: [PATCH 13/14] blog: simplify the background and change the structure Signed-off-by: hi-rustin --- _posts/2024-02-01-feedback-on-cargo-info.md | 140 ++------------------ 1 file changed, 11 insertions(+), 129 deletions(-) diff --git a/_posts/2024-02-01-feedback-on-cargo-info.md b/_posts/2024-02-01-feedback-on-cargo-info.md index 6712296..386430e 100644 --- a/_posts/2024-02-01-feedback-on-cargo-info.md +++ b/_posts/2024-02-01-feedback-on-cargo-info.md @@ -9,10 +9,18 @@ tags: - CLI --- -# Summary +# 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. + +[crates.io]: https://crates.io +[cargo#948]: https://github.com/rust-lang/cargo/issues/948 + Example usage: ```console @@ -69,133 +77,7 @@ owners: | dependencies: | All dependencies | It indicates what it depends on. | | owners: | Owners | It indicates who maintains the crate. | -# Motivation - -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. - -[crates.io]: https://crates.io -[cargo#948]: https://github.com/rust-lang/cargo/issues/948 - -# Guide-level explanation - -## 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. - -```console -$ 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: - windows-sys@0.52 -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. - -```console -$ 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: - windows-sys@0.52 -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 home@0.5.9` -``` - -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. - -[rustup repository]: https://github.com/rust-lang/rustup - -## 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. - -```console -$ 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: - windows-sys@0.52 -``` - -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. - -[cargo repository]: https://github.com/rust-lang/cargo - -## 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`. - -```console -$ cargo info home@0.5.9 - 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: - windows-sys@0.52 -owners: - alexcrichton (Alex Crichton) - brson (Brian Anderson) - LucioFranco (Lucio Franco) - ehuss (Eric Huss) - kinnison (Daniel Silverstone) - rust-lang-owner -``` - -[Cargo documentation]: https://doc.rust-lang.org/cargo/reference/pkgid-spec.html - -# Reference-level explanation +# Some important notes ## Downloading the crate from any Cargo compatible registry @@ -274,7 +156,7 @@ required by [Poetry]: https://python-poetry.org/ -# Unresolved questions +# Known Points of Concern 1. Report crates metrics? [cargo-information#20] From 519034d2c16ec4ea517512571b70165e04f56a50 Mon Sep 17 00:00:00 2001 From: hi-rustin Date: Tue, 20 Feb 2024 20:57:47 +0800 Subject: [PATCH 14/14] blog: add reminder Signed-off-by: hi-rustin --- _posts/2024-02-01-feedback-on-cargo-info.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/_posts/2024-02-01-feedback-on-cargo-info.md b/_posts/2024-02-01-feedback-on-cargo-info.md index 386430e..311494e 100644 --- a/_posts/2024-02-01-feedback-on-cargo-info.md +++ b/_posts/2024-02-01-feedback-on-cargo-info.md @@ -9,6 +9,11 @@ tags: - CLI --- +# 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.