tools (cargo | versioning)
min_rust_versionAdd rust field to the package section of Cargo.toml which will be used to
specify crate's Minimum Supported Rust Version (MSRV):
[package]
name = "foo"
version = "0.1.0"
rust = "1.30"
Currently crates have no way to formally specify MSRV. As a result users can't check if crate can be built on their toolchain without building it. It also leads to the debate on how to handle crate version change on bumping MSRV, conservative approach is to consider such changes as breaking ones, which can hinder adoption of new features across ecosystem or result in version number inflation, which makes it harder to keep downstream crates up-to-date. More relaxed approach on another hand can result in broken crates for user of older compiler versions.
If you target a specific MSRV add a rust field to the [package] section of
your Cargo.toml with a value equal to the targeted Rust version. If you build
a crate with a dependency which has MSRV higher than the current version of your
toolchain, cargo will return a compilation error stating the dependency and
its MSRV. This behavior can be disabled by using --no-msrv-check flag.
During build process (including run, test, benchmark, verify and publish
sub-commands) cargo will check MSRV requirements of all crates in a dependency
tree scheduled to be built or checked. Crates which are part of the dependency
tree, but will not be built are excluded from this check (e.g. target-dependent
or optional crates).
rust field should respect the following minimal requirements:
package.rust field
became a warning instead of an error).rust = "1.27" and edition = "2018" is an invalid one.The value of rust field (explicit or automatically selected by cargo) will
be used to select appropriate dependency versions.
For example, let's imagine that your crate depends on crate foo with 10 published
versions from 0.1.0 to 0.1.9, in versions from 0.1.0 to 0.1.5 rust
field in the Cargo.toml sent to crates.io equals to "1.30" and for others to
"1.40". Now if you'll build your project with e.g. Rust 1.33, cargo will select
foo v0.1.5. foo v0.1.9 will be selected only if you'll build your project with
Rust 1.40 or higher. But if you'll try to build your project with Rust 1.29 cargo
will issue an error.
rust field value will be checked as well. During crate build cargo will check
if all upstream dependencies can be built with the specified MSRV. (i.e. it will
check if there is exists solution for given crates and Rust versions constraints)
Yanked crates will be ignored in this process.
Implementing this functionality hopefully will allow us to close the long-standing debate regarding whether MSRV bump is a breaking change or not and will allow crate authors to feel less restrictive about bumping their crate's MSRV. (though it may be a useful convention for post-1.0 crates to bump minor version on MSRV bump to allow publishing backports which fix serious issues using patch version)
Note that described MSRV constraints and checks for dependency versions resolution
can be disabled with the --no-msrv-check option.
cargo publish will check that upload is done with a toolchain version specified
in the rust field. If toolchain version is different, cargo will refuse to
upload the crate. It will be a failsafe to prevent uses of incorrect rust values
due to unintended MSRV bumps. This check can be disabled by using the existing
--no-verify option.
rust field mandatoryIn future (probably in a next edition) we could make rust field mandatory for
a newly uploaded crates. MSRV for older crates will be determined by the edition
field. In other words edition = "2018" will imply rust = "1.31" and
edition = "2015" will imply rust = "1.0".
cargo init would use the version of the toolchain used.
cfg-based MSRVsSome crates can have different MSRVs depending on target architecture or enabled features. In such cases it can be useful to describe how MSRV depends on them, e.g. in the following way:
[package]
rust = "1.30"
[target.x86_64-pc-windows-gnu.package]
rust = "1.35"
[target.'cfg(feature = "foo")'.package]
rust = "1.33"
All rust values in the target sections should be equal or bigger to a rust value
specified in the package section.
If target condition is true, then cargo will use rust value from this section.
If several target section conditions are true, then maximum value will be used.
Some crates may prefer to target only the most recent stable or nightly toolchain.
In addition to the versions we could allow stable and nightly values to declare
that maintainers do not track MSRV for the crate.
For some bleeding-edge crates which experience frequent breaks on Nightly updates
(e.g. rocket) it can be useful to specify exact Nightly version(s) on which
crate can be built. One way to achieve this is by using the following syntax:
Such restrictions can be quite severe, but hopefully this functionality will be used only by handful of crates.
cargo publish with rust = "stable" can be too
conservative.cfg attributes as proposed in RFC 2523.Previous proposals:
rust vs rustc vs min-rust-version