RFC: Minimum Supported Rust Version

[newpavlov]

This RFC adds an ability to specify Minimum Supported Rust Version (MSRV) in Cargo.toml using rust field:

[package]
name = "foo"
version = "0.1.0"
edition = "2018"
rust = "1.35"

Rendered

Tracking issue

Internals discussion

Edit: FCP proposal #2495 (comment)

[Nemo157]

What is the intended meaning of "checked that crate indeed can be built with the specified version", use rustup to install the specified version and attempt to package with it?

It seems like this could be covered by the error listed above:

In case if you have rust="stable", but execute cargo publish with Nigthly toolcahin you will get an error.

if you have rust = "1.30" then you will only be allowed to publish when using Rust v1.30.

[newpavlov]

I had in mind that cargo publish in addition to the current toolchain will build crate with MSRV toolchain with some additional checks.But you are right, if we extend behaviour described for "stable"/"nightly" (i.e. you can cargo publish only using MSRV toolchain), then describe checks will be redundant. I'll update RFC accordingly.

[shingtaklam1324]

Shouldn't this allow a full string, like the date of a nightly build? For some tools which basically is built for a specific nightly (clippy comes to mind) this can be a useful tool. As well as that, it would be useful as AFAIK 1.xx.0-nightly refers to all of the nightlys that have been built during the six weeks.

---

Edit: I see this is mentioned later on, but shouldn't it be a Rust version and not just any semver anyways?

Also there is a typo there with the spelling of nightly.

[newpavlov]

I don't see much merit in using 1.xx.0-nightly versions instead of the simple "nightly". I think it's a reasonable assumption that nightly toolchain will stay fairly up-to-date for most of the developers, and for crates which experience frequent breakage it's better to have finer-grained control provided by nightly: 2018-01-01 approach.

Thank you for noticing the typo, I'll fix it!

[shingtaklam1324]

Do you mean the current nightly toolchain? Because during the lifetime of Rust 1.xx stable, 1.xx+2 is the nightly version in use. This would then disallow the publishing to those crates to crates.io if it checks against the current stable.

[newpavlov]

No, I meant stable. If we have stable Rust 1.35 and nightly 1.37, using rust="1.37" implying nightly toolchain will result in an ambiguity when stable Rust 1.37 will be published. So if crate depends on Nightly features, then it will have to use rust="nightly"/"nightly: ...".

[kennytm]

I prefer we reuse the existing [target.*] section for this:

rust = "1.30"

[target.x86_64-pc-windows-gnu]
rust = "1.35"

[target.'cfg(feature = "foo")']
rust = "1.33"

(Note that cargo should either fully support [target.'cfg(feature = "foo")'.dependencies] or outright reject it)

[newpavlov]

Hm, reusing target is a good idea. I'll replace rust-case with your proposal.

As for [target.'cfg(feature = "foo")'.dependencies], while it's somewhat redundant to optional = true dependencies + foo = [".."], I think it could provide a better flexibility in specification of optional dependencies (e.g. add dependency only for given target if feature is enabled), so in my opinion it should be supported.

[kennytm]

Using .. as inclusive range in Rust is gonna be confusing. Could we incorporate the semver operators instead?

nightly: >=2018-01-01, <=2018-01-15

or

>=nightly-2018-01-01, <=nightly-2018-01-15

(every new nightly is considered a major version for sure.)

[newpavlov]

I am not particularly attached to the proposed syntax (I think that exact versions ("nightly: 2018-01-01") will be used much more often than other variants), so probably using semver operators will be indeed a better choice.

Though, after some thought I've started to worry about inconsistency between how "stable" and "nightly" work. I think it will be better to make "nightly" work in the same fashion as "stable", i.e. cargo publish will select version of the currently used nightly toolchain. "nightly: *" in turn will be used to specify "all nightly Rust versions". cargo init should probably use the latter variant on nightly. What do you think?

[kennytm]

Sounds good to me, though it makes me think if it makes sense to mix both stable and nightly in the same line?

rust = "1.26, nightly: >=2017-01-01"

[newpavlov]

Hm, any use-case examples? As I see it, if code enables nightly features it can't work on stable, and if it works on stable it should work on nightly. Well, excluding potential nightly regressions of course, which I think we can safely ignore.

UPD: Also there is a very old nightly versions possibility, but I think we can ignore such cases as well. Though from consistency point of view, such pattern could be allowed, but I am not sure if it's worth the additional complexity.

[kennytm]

@newpavlov num-traits uses a build script to determine whether to enable i128, which covers both stable and nightly. Though the said build script could emit an error itself meaning there's probably no real use case 🙃.

[crlf0710]

I think i like the key name be rustc better (or it will become problematic for alternative compilers like mrustc or something like that.)

I actually think the channels should not be mixed in. Since it's using semver, cargo init can just write "1" to represent all available rustc versions, right?

I also think that if a crate is nightly only. It can mark itself in an permanently unstable attribute, maybe something like nightly-rustc = ">=20180707" . And only nightly cargo can recognize and publish those crates, which is ok i think.

[newpavlov]

Personally I don't have a strong preference regarding the name, so it could be changed on implementation. But if we consider other compilers, then in my opinion rust fields makes more sense, as it can be interpreted as a version number of "rust specification", which currently provided in the form of the reference implementation. We could extend rust field to support experimental features of other compilers, e.g. in this form rust = "mrustc: ...".

Channels are mostly for convenience and providing sensible default option. Using "1.0" as a default value will result in too relaxed constraints on crate versions, thus making the feature significantly less useful in a long run. While the proposed channel handling will result in a too conservative constraint, at least we'll know for certain that crate can be built with a specified version.

As for nightly-rustc I don't see much benefit in introducing additional field, except making rust field pure-semver, which has arguable merit. Stable/nightly requirements are mutually exclusive, so there shouldn't be any problems in keeping them in one field. Also it will simplify explanation of this feature.

[newpavlov]

@aturon
Can this feature be implemented and introduced as part of the Rust 2018 release? (even in the form of "dumb fields") The proposed rust field is required, so it will be nice to make it optional only for 2015 edition.

[phaylon]

It might be nice if there were an env|cli|profile option to have cargo emit an error or warning if the used toolchain is newer than specified for cargo check and test. So you have the chance of catching it early if you want.

[kinggoesgaming]

This should also help with crates.io have a badge for it too

[Ortham]

Shouldn't this be "foo v0.1.10 if you build your project with Rust 1.40 or later" (1.30 -> 1.40)?

[newpavlov]

Yes, you are right. Thank you for noticing the typo!

[teiesti]

I don't like this kind of automatic conversion from stable to e.g. 1.30. I think it is counter-intuitive.

Instead, I would like to propose a slightly more complicated approach with a huge effect on the question raised above (namely "Is a MSRV change a breaking change for a crate which then requires a major version bump?"). Let me give an example:

1. A user might declare the MSRV to be 1.30. This means that the crate which is published to crates.io can be compiled by every compiler between 1.30 (inclusive) and 2 (exclusive), just as semantic versioning suggests. If he uploads the next (patch or minor) version of the same crate, the MSRV must be equal to or smaller than 1.30. Everything else would be considered a breaking change. If he uploads the next major version, of course he's free to change the MSRV.

2. A user might also declare the MSRV to be stable. When published to crates.io, stable is converted to stable(1.30) with 1.30 being the current stable release. This means that the published artifact will work with a compiler between version 1.30 (inclusive) and 2 (exclusive). So far no difference! Now, times passes and a new stable compiler (1.31) was published. The crate artifact which was already published still works with a compiler between 1.30 (inclusive) and 2 (exclusive). But if the crate author opts to publish a new crate version, the MSRV for the new artifact is automatically raised to stable(1.31) which means that it guarantees to work with a compiler version between 1.31 (inclusive) and 2 (exclusive). This MSRV change wound not be considered a breaking change since it was already declared before.

Therefore a crate author has to options:

1. Fix the MSRV to a specific version, e.g. 1.30.
2. Fix the MSRV to stable which means that a future crate version might require a future compiler version (which is at least stable).

Anyway, changing the MSRV is considered to be a breaking change which requires a major version bump. (Someone might relax this requirement as I did in the example above and allow a change from e.g. stable to 1.32 or 1.31 to 1.30, since that is no compatibility problem).

I think, one could take this idea even further and allow labels like stable - 0.4 which means that, a future crate works with the current version minus 4 minor versions. I think this is even a reasonable alternative to LTS releases as proposed in #2483. (Or we could then say that lts is stable minus one year or another reasonable time considered to be a long term...)

[teiesti]

By the way, this idea does not work for nightly because the nightly compiler does not guarantee backward compatibility.

[newpavlov]

Probably my wording was not clear enough, but I've meant almost exactly the same behaviour as was described by you. Automatic conversion from stable to 1.30 happens if user executes cargo publish with 1.30 toolchain, in his local Cargo.toml rust field will be left unchanged, equal to stable. After that user makes some changes to the crate and updates toolchain to stable 1.33. Now on cargo publish for the next crate version stable will be converted to 1.33, which will mean >=1.33.0, <2.0.0.

For nightlies I currently propose to use nightly: * as a default option for crates which require nightly compiler, which will mean "any Nightly version".

[newpavlov]

As for LTS releases, they are not only about MSRV, they will also serve as a synchronization point for crate authors and package authors (think Debian). LTS also means that crucial updates (e.g. security or soundness fixes) will be backported to those versions. So I don't think that stable - 0.4 will be able to cover all LTS use-cases.

[teiesti]

Probably my wording was not clear enough, but I've meant almost exactly the same behaviour as was described by you.

To be honest, I am still not sure that we are talking about the same thing: I think, the crucial difference is that in the first case (rust = 1.30) the published MSRV on crates.io is 1.30, while in the second case (rust = stable), the published MSRV is stable(1.30). To be even clearer: 1.30 is not at all equal to stable(1.30). While they behave equal when it comes to the crate's current version, they are different for the next (patch or minor) version: In the first case the MSRV will be 1.30, while in the second case it might be 1.30 or stable(1.31) or even 1.31. Therefore, the crate user can determine from the difference between 1.30 and stable(1.30) how the crate author answers the question "Is an MSRV change a breaking change?". In the first case, the answer is yes, in the second case it is no!

I would like to see a whole passage dedicated to that matter which leaves no room for interpretation... ;-)

I would also like to see a passage dedicated to "version arithmetic" which covers e.g.:

• Under which circumstances is a MSRV downgrade/upgrade a breaking change?
  • 1.30 can be 1.29, 1.28.1, ... in the next crate version.
  • stable(1.30) can be 1.29, 1.28.1, ... or stable(1.30.1), stable(1.31), ... or 1.30, 1.30.1, 1.31, ... in the next crate version (as long as the rustc is already stabilized).
• What if crate A depends on crate B and crate C. What are the requirements for the MSRV of crate A given the MSRV of B and C?
  • Something like MSRV(A) <= min(MSRV(A), MSRV(B)). We need a (partial?) order here!
• (How) is it possible to calculate with MSRVs? Examples:
  • stable(1.30.1) - 0.0.1 = stable(1.30)
  • stable(1.30) - 0.3 = stable(1.27)
  • stable(1.30.1) - 0.0.2 = stable(1.30.0) Does this even work?
  • stable(1.30) - 1 = undefined

As for LTS releases, they are not only about MSRV, they will also serve as a synchronization point for crate authors and package authors (think Debian). LTS also means that crucial updates (e.g. security or soundness fixes) will be backported to those versions.

You are right. But I highly doubt the utility of LTS releases for other cases than language version requirements:

• Take the argument about patches that are backported to LTS. If such a package becomes necessary, Debian (or anyone else) will need to adopt the fixed LTS version. In that case, they can also adopt the current stable version, since Rust is guaranteed to be backward-compatible (in version 1.x). LTS releases are even counterproductive in this use case, since they encourage not upgrading to the current release and therefore increase the number of old compilers out there.
• Take the argument about synchronization points. We already have them, they are called "editions". (We could also publish guideline that give suggestion when a good times has come to update and how long crates should support old compiler versions. This could be done in an RFC which depends on things like stable(1.30) - 0.2.)

[teiesti]

Okay, I've re-read your RFC and I think now that You've mentioned some of my points. But perhaps, they are still useful to clarify things... ;-)

Btw Thanks for Your effort!

[newpavlov]

Hm, I don't quite get stable(x) functionality then. The only difference which I can see is that stable(1.30) will hint that rust field was automatically inserted by cargo, otherwise behavior looks similar to me. I'll try to describe current proposal a bit better in a separate PR to my repo. I'll link it later and I will be happy to hear your comments on which parts you think will need additional clarification.

how the crate author answers the question "Is an MSRV change a breaking change?"

As I see it, if public API does not change, then MSRV change will never (well, except the initial migration to using rust field) be a breaking change, be it upgrade or downgrade. Dependency versions resolution algorithm will handle a selection of appropriate versions for current toolchain automatically.

What if crate A depends on crate B and crate C. What are the requirements for the MSRV of crate A given the MSRV of B and C?

Don't forget that dependency can be defined as 0.x, so you have not one version, but a set. Thus formula will be MSRV(A) >= max(min( [MSRV(A1), ..MSRV(An)] ), min( [MSRV(B1), ..MSRV(Bn)] )). For stable versions order should be quite simple and you even don't have to calculate it explicitly. Running cargo publish with your MSRV toolchain will automatically check if non-empty solution for dependency versions exists.

But with "nightly versions" extension things become more complex. You'll have to check that your MSRV condition contains only such nightly versions which can be covered by all of your dependencies.

(How) is it possible to calculate with MSRVs?

I am not sure this feature will pulls its weight. Plus it can be added later in a backwards compatible way by a separate proposal.

[teiesti]

I was thinking about the theoretical foundations of my proposal and I came up with this article. It is some kind of pre-work for my proposal in this thread but I think its worth sharing here. (Anywhere, I'll try to write another article surrounding these ideas soon.)

An internals thread for a discussion about the article can be found here.

[fintelia]

I like the idea of flagging supported compiler versions, but I don't quite understand how a crate would actually be able to use this in practice if the list of supported versions has to go in the published Cargo.toml file itself.

Typically when publishing a nightly only crate, I know it works for the current nightly and that it will continue to work for all future nightlies until there is a breaking change. With this design, it seems like I'd need to publish a new version of the crate every day with an updated Cargo.toml saying that the new nightly also works or else my users would be unable to upgrade their compiler.

[newpavlov]

As I see it, the main use-case will be to provide exact nightly version, on which crate is developed and tested. So e.g. if you depend on rocket x.y.z which is developed and published with nightly-2019-02-01 toolchain, then your crate will have to be developed with the same toolchain. This will result in a soft synchronization of nightly versions used across nightly crates ecosystem. (e.g. crates will update nightlies ever 2-3 weeks or so, not every night)

If your crate does not experience breakage too often, then you can use default nightly: * option.

[fintelia]

Using the field to indicate a known good nightly version seems reasonable.

However, I'd be a concerned about it factoring into version resolution then ("stage 3" of the RFC). The entire ecosystem of nightly crates would have to update in lockstep or else become mutually incompatible. Further, trying out new nightlies would require waiting for all your dependencies to be updated. Basically, you'd no longer be running on the nightly channel but instead a sort of "monthly" channel which lacked both the stability of stable and the quick bug fixes of nightly.

[newpavlov]

I think most of the nightly crates will just use "nightly: *", some may use ranges (though properly testing it will not be easy), finer grained nightly selection will be used only be a handful of crates with rare intersections with each other. Plus do not forget that you always can disable MSRV constraint in dependency versions resolution with --no-msrv-check flag.

[fintelia]

I'm sorry, I'm still not fully understanding. Lets use a concrete example. I maintain the rahashmap crate which depends on some rather unstable features and so breaks every couple weeks. The last time this happened, I fixed the issue and promptly published a new version. This new version supports nightly-2018-07-10, nightly-2018-07-11, and all future nightlies until another breaking change happens. If this RFC & extension were implemented, what would be the correct value for MSRV?

[newpavlov]

The problem with "all future nightlies until another breaking change happens" is that this constraint can be properly expressed at the moment of crate publishing, as you don't know when breaking change will happen. The closest thing which we can get is to use rust="nightly: >= 2018-07-10" (it's mentioned in the extension). On the next breaking change you'll publish rust="nightly: >= 2018-08-10". So assuming that user keeps all his dependencies updated, with new toolchain he'll use newer crate version, and on old toolchain the older crate version will be used. But nightly: * will not be much worse and will require significantly less effort from you.

But this approach feels quite fragile. To reliably solve this problem we will need an additional channel for notifying users "this crate broke on the following nightly versions" which can't be done via Cargo.toml.

[vi]

Shall it support usual version syntax syntax like =1.35, ^1.35, 1.35.0?

[kinggoesgaming]

Shall it support usual version syntax syntax like =1.35, ^1.35, 1.35.0?

@vi

Even if it was supported, I don't think it would something that would be useful, as it is only marking the absolute minimum version of Rust needed. The support for that syntax makes more sense for crates.

[dekellum]

If you accept the fact that rust has in the past and will in the future make non-backward compatible changes, then a maximum supported version (or in other words a complete dependency range with minimum and maximum) is useful for crate lib authors. See also rust-lang/rust#52320 for implications regarding how this is a two way street of effects.

[fintelia]

@dekellum Take a look at the inline review comments about nightly versioning above. Specifying a maximum supported version in the Cargo.toml of a crate generally isn't helpful: you typically don't know when the next relevant breaking change will happen. And once you've published a crate, if there is later a breaking change, you can't go back and change it to say what the maximum supported version is.

[dekellum]

@fintelia, I respectively still think a maximum supported version is useful and applicable. I/you can publish a patch release (e.g. 1.2.1 for a 1.2.0 crate) with a new maximum version bound, once you determine that a stable or nighly rust has a breaking change that effects the lib.

[newpavlov]

I/you can publish a patch release (e.g. 1.2.1 for a 1.2.0 crate) with a new maximum version bound

The problem is that on "broken" newer stable Rust cargo will select 1.2.0 crate, because your 1.2.1 will be excluded from versions resolution due to the maximum bound, thus in your example version 1.2.1 becomes useless.

Either way maximum bounds can be introduced in a separate RFC, after baseline version of this proposal will be implemented.

[dekellum]

Thanks @newpavlov. I agree that maximum bound could be introduced later/incrementally (edit 3, but see below, I think it should be included now.)

We know that cargo could be made a lot smarter in version resolution. At the very least my 1.2.1 offers cargo readable documentation on late found maximum rust bound, which must be better than no information, even if we are not yet certain how to use it!

Edit 1: The 1.2.1 change is not dissimilar to after-the-fact narrowing of a regular crate dependency, (e.g. foodep = "^1.2" later changed to foodep = ">= 1.2.0, < 1.4.0") in a later patch, other than the likehood of cargo being able to resolve it. Another possible solution is cargo or crates.io support for updating crates.io hosted maximum bounds metadata, after publishing, which is also applicable to regular crate dependency and rust itself.

Edit 2: To update metadata even without explicit cargo or crates.io support, I just publish an updated 1.2.1 and then yank 1.2.0.