Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/foresterre/cargo-msrv
🦀 Find the minimum supported Rust version (MSRV) for your project
https://github.com/foresterre/cargo-msrv
cargo cargo-msrv cli hacktoberfest msrv rust rust-lang rust-tools
Last synced: about 1 month ago
JSON representation
🦀 Find the minimum supported Rust version (MSRV) for your project
- Host: GitHub
- URL: https://github.com/foresterre/cargo-msrv
- Owner: foresterre
- License: apache-2.0
- Created: 2019-09-29T06:24:29.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-25T16:35:59.000Z (about 2 months ago)
- Last Synced: 2024-09-29T20:41:10.701Z (about 2 months ago)
- Topics: cargo, cargo-msrv, cli, hacktoberfest, msrv, rust, rust-lang, rust-tools
- Language: Rust
- Homepage: https://foresterre.github.io/cargo-msrv
- Size: 4.01 MB
- Stars: 860
- Watchers: 8
- Forks: 27
- Open Issues: 68
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# cargo-msrv
This crate can assist you in finding the Minimum Supported Rust Version for a crate.
In this readme you'll find everything to get you started. You can find more detailed explanations in the
[cargo-msrv book](https://foresterre.github.io/cargo-msrv/index.html).
###
- 📜 [A short history](#a-short-history)
- 💿 [Install](#install)
- 🔩 [Prerequisites](#prerequisites)
- ✨ [Preview](#preview)
- ⭐ [Usage](#usage)
- 🤖 [JSON output format](#json-format)
- 🫶 [License](#license)
### A short history
_An [excerpt](https://foresterre.github.io/posts/puzzle-sharing-declarative-args-between-top-level-and-subcommand/)_
> `cargo-msrv` was originally born out of a desire to find the MSRV for a Rust project (more specifically package). MSRV
> stands for "minimal supported Rust version" and is the earliest or oldest version supported by a Rust project. For
> different projects this may mean different things, but for this post I will consider "support" as "does compile with a
> Rust toolchain of a certain version".
>
> Fast forward a few years, and the MSRV has become somewhat more ubiquitous which can also be seen by its inclusion
> into Cargo as the [rust-version](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field). Over
> time some additional tools were added to `cargo-msrv`. One of these was the `cargo msrv verify` subcommand.
>
> This subcommand can be used to check whether a Rust project supports its defined MSRV (e.g. via this `rust-version`
> field in the Cargo manifest). For example, in a CI pipeline you can use this to check whether your project works for
> the
> version you promised to your users.
>
> Originally, I kept the `cargo msrv` top level command aside from the subcommands for backwards compatibility reasons.
> In hindsight I probably shouldn't have done that, but as is, their coexistence at least provides me with the
> opportunity
> to write this blog post 😅.
>
> **How cargo msrv works**
>
>I described the "support" from "minimal supported Rust version" (MSRV) above as the somewhat simplified "does compile
> with a Rust toolchain of a certain version".
>
>You may write that as a function like so: `fn is_compatible(version) -> bool`. If you run this test for some Rust
> version, when the function produces the value `true`, then we consider the Rust version to be supported. If instead
> the
> function produces the value `false`, then the Rust version is not supported.
>
>`cargo msrv` specifically searches for the _minimal_ Rust version which is supported by a given Rust project. While
> there are some caveats, we build upon
> Rust's [stability promise](https://blog.rust-lang.org/2014/10/30/Stability.html#committing-to-stability) . In our case
> that is the idea that Rust versions are backwards compatible.
>
>For a simple example to determine an MSRV, you can linearly walk backwards from the most recent Rust version to the
> earliest. When your project doesn't compile for a specific Rust version, then the last version that did compile can be
> considered your MSRV.
>
>Let's make it a bit more concrete with an example. For this example, we assume that Rust the following Rust versions
> exist: `1.0.0` up to and including `1.5.0`.
>
>Consider a project which uses the [Duration](https://doc.rust-lang.org/std/time/struct.Duration.html#) API which was
> stabilised by [Rust 1.3.0](https://github.com/rust-lang/rust/blob/master/RELEASES.md#version-130-2015-09-17) (and
> nothing more recent 😉).
>
>Then, if you would compile this project with Rust version from most recent to least recent, you would expect the
> following to happen:
>
>- `is_compatible(Rust 1.5.0)` returns `true` ✅
>- `is_compatible(Rust 1.4.0)` returns `true` ✅
>- `is_compatible(Rust 1.3.0)` returns `true` ✅
>- `is_compatible(Rust 1.2.0)` returns `false` ❌ ("Duration is not stable")
>- `is_compatible(Rust 1.1.0)` returns `false` ❌
>- `is_compatible(Rust 1.0.0)` returns `false` ❌
>
>Since we only care about the _minimal_ Rust version, you could have stopped searching after compiling Rust 1.2.0; Rust
> 1.3.0 was the earliest released Rust version which worked.
>
>In reality doing a linear search is quite slow (at the time of writing, there are 79 minor versions), so we primarily
> use a binary search instead to incrementally reduce the search space.
>
>`cargo msrv verify` works quite similar to "finding the MSRV", but instead of running a search which produces as
> primary output the MSRV, in this case the MSRV is already known in advance. So given a `MSRV` of `1.3.0` we just run
> the
`is_compatible(Rust 1.3.0)` function once. If it returns `true` we can say that the 1.3.0 is an acceptable MSRV (
> although not necessarily strictly so). More importantly, if it returns false, then the specified version is actually
> not
> supported, and thus can not be an MSRV).
### Install
#### cargo ([crates.io source](https://crates.io/crates/cargo-msrv))
| cargo | supported | command |
|-------------|-----------|---------------------------------------|
| stable | 💚 | `$ cargo install cargo-msrv --locked` |
| development | ❌ | |
#### cargo ([git source](https://github.com/foresterre/cargo-msrv))
| cargo | supported | command |
|-------------|-----------|-----------------------------------------------------------------------------------------------|
| stable | 💚 | `$ cargo install --git https://github.com/foresterre/cargo-msrv.git --tag v0.16.2` cargo-msrv |
| development | 💚 | `$ cargo install --git https://github.com/foresterre/cargo-msrv.git` cargo-msrv |
#### [cargo-binstall](https://github.com/cargo-bins/cargo-binstall)
| cargo | supported | command |
|-------------|-----------|-------------------------------------------------------------|
| stable | 💚 | `$ cargo binstall --version 0.16.2 --no-confirm cargo-msrv` |
| development | ❌ | |
#### Arch Linux [extra repository](https://archlinux.org/packages/extra/x86_64/cargo-msrv/)
* `pacman -S cargo-msrv`
#### Docker
You can use the following commands for building and running via Docker:
* `$ docker build -t cargo-msrv .`
* `$ docker run -t -v "$(pwd)/Cargo.toml":/app/Cargo.toml cargo-msrv`
Docker images are also available on [Docker Hub](https://hub.docker.com/r/foresterre/cargo-msrv).
### Prerequisites
[Rustup](https://rustup.rs/) is required for the `cargo msrv (find)` and `cargo msrv verify` commands.
### Preview
[](https://asciinema.org/a/679852)
### Usage
* [`cargo msrv find`](https://foresterre.github.io/cargo-msrv/commands/find.html)
or [`cargo msrv find --linear`](https://foresterre.github.io/cargo-msrv/commands/find.html) to find the MSRV for a
Cargo project in your current working directory.
* [`cargo msrv --path find`](https://foresterre.github.io/cargo-msrv/commands/find.html) to find the MSRV for a
Cargo project in the `` directory.
* [`cargo msrv find -- `](https://foresterre.github.io/cargo-msrv/commands/find.html) to use `` as the
compatibility check which decides whether a Rust version is
compatible or not. This command should be runnable through rustup as `rustup run `.
* Example: `cargo msrv find -- cargo check --tests`.
* [`cargo msrv verify`](https://foresterre.github.io/cargo-msrv/commands/verify.html) to verify the MSRV as specified
by a crate author\
* A crate author may specify the MSRV using the `package.rust-version` (Rust >=1.56) or the `package.metadata.msrv`
key in the 'Cargo.toml' manifest. See
the [book](https://foresterre.github.io/cargo-msrv/commands/list.html#description) for a more detailed
description.
* [`cargo msrv list`](https://foresterre.github.io/cargo-msrv/commands/list.html) to list the MSRV's of your
dependencies as specified by their authors
* [`cargo msrv show`](https://foresterre.github.io/cargo-msrv/commands/show.html) to show the currently specified MSRV
Please refer to the [commands](https://foresterre.github.io/cargo-msrv/commands/index.html) chapter in the cargo-msrv
book for more detailed descriptions of the supported (sub) commands.
**Options**
```
Find your Minimum Supported Rust Version!
Usage: cargo msrv [OPTIONS]
Commands:
find Find the MSRV
list Display the MSRV's of dependencies
set Set the MSRV of the current crate to a given Rust version
show Show the MSRV of your crate, as specified in the Cargo manifest
verify Verify whether the MSRV is satisfiable
help Print this message or the help of the given subcommand(s)
Options:
--path
Path to cargo project directory
--manifest-path
Path to cargo manifest file
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
User output options:
--output-format
Set the format of user output
[default: human]
Possible values:
- human: Progress bar rendered to stderr
- json: Json status updates printed to stdout
- minimal: Minimal output, usually just the result, such as the MSRV or whether verify succeeded or failed
--no-user-output
Disable user output
Debug output options:
--no-log
Disable logging
--log-target
Specify where the program should output its logs
[default: file]
[possible values: file, stdout]
--log-level
Specify the severity of logs which should be
[default: info]
[possible values: trace, debug, info, warn, error]
You may provide a custom compatibility `check` command as the last argument (only
when this argument is provided via the double dash syntax, e.g. `$ cargo msrv -- custom
command`.
This custom check command will then be used to validate whether a Rust version is
compatible.
A custom `check` command should be runnable by rustup, as they will be passed on to
rustup like so: `rustup run `. NB: You only need to provide the
part.
By default, the custom check command is `cargo check`.
```
### JSON format
JSON output may be enabled by providing the `--output-format json` flag: `cargo msrv find --output-format json`.
Events are printed as json lines. The event type is indicated by the `type` key.
Please see the [Output formats](https://foresterre.github.io/cargo-msrv/output-formats/index.html) and
[Output format: JSON](https://foresterre.github.io/cargo-msrv/output-formats/json.html) chapters of the
book for documentation of this output format.
### License
Licensed under either of
* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
#### Contribution
Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you, as defined in the Apache-2.0
license, shall be dual licensed as above, without any additional terms or
conditions.