Tracking issue for MSRV project

[adamgreig]

This is a tracking issue for progress on #443.

Here's a link to the project document which explains the project in more detail.

How To Help

We're trying to make sure all WG crates have a well defined Minimum Supported Rust Version (MSRV), which is the oldest version of Rust that can build the crate and run its tests. All our crates should have their MSRV defined in their documentation, and have their CI system automatically run the tests using the MSRV to make sure we don't accidentally break it.

Getting Started

Thank you for your interest in helping! Depending on your skill level, you might find it easiest to just jump in, or you might want more assistance getting going. If you want to just jump in, pick an unclaimed repository from the list below and follow the steps. You can post here that you're working on a project, or just go ahead and open a PR if it's fairly quick.

If you'd like more assistance, please either leave a comment here, or message @adamgreig:matrix.org on the Rust Embedded Matrix, and we'll get you started!

1. Check Current Status

It might be that your repository already has its MSRV documented and/or tested, so it's worth reviewing the steps below quickly to see if this is the case. For repositories where the MSRV is documented and tested, we can tick them off this list with no further work. Please leave a comment here if that's the case!

Otherwise, go ahead and fork the repository from GitHub.

2. Finding the MSRV

First, make sure you can build the crate and run the tests. For most WG repositories, that means running their ci/script.sh script:

$ ci/script.sh

Many of our crates build for multiple targets, which is usually defined in their .travis.yml CI configuration file. To run your build for a different target, for example thumbv6m-none-eabi:

$ env TARGET=thumbv6m-none-eabi ci/script.sh

Once the build works on your default Rust toolchain, you'll need to test it on other toolchains. To install a custom toolchain (here 1.40.0), a target for it, and then run tests with it:

$ rustup toolchain install 1.40.0
$ rustup target add thumbv6m-none-eabi --toolchain 1.40.0
$ env TARGET=thumbv6m-none-eabi RUSTUP_TOOLCHAIN=stable ci/script.sh

Once you have this working, the game is to keep reducing the Rust version until it stops working, at which point you've found the MSRV. It might stop working for a trivial reason that is easily fixed, in which case it could be worth fixing and lowering the MSRV further, but we'll have to decide such issues on a case-by-case basis. We don't expect to go any lower than 1.31 (the first 2018 edition release), but would hope to get at least 1.40 in every case. Ten releases to try!

On the other hand, if this doesn't work for some reason (some projects have more complicated CI setups), please leave a comment here or open an issue on the relevant repository and we'll help figure out what to do.

3. Documenting the MSRV

Once the MSRV is found, add the following snippet to the project's README.md, src/lib.rs, or equivalent documentation:

# Minimum Supported Rust Version (MSRV)

This crate is guaranteed to compile on stable Rust 1.31.0 and up. It *might*
compile with older versions but that may change in any new patch release.

4. Testing the MSRV

To have the CI system run the tests on the MSRV, add the following snippet to the repository's .travis.yml configuration file. Note that the matrix section probably already exists; you want to add a new entry to it for the MSRV test.

matrix:
  include:
    # MSRV
    - env: TARGET=thumbv7-none-eabi
      rust: 1.31.0
    # ...

Many projects test on multiple targets, so add an MSRV entry for each target. If in doubt, seek advice on this issue or on the specific project.

5. Finishing Up

Make a GitHub PR with your changes and link it here. We'll use the PR to review and discuss the change and then get your changes merged in.

Crates Checklist

We'll update this list with a user who's working on that repository, a link to the relevant PR when opened, and tick off crates that are complete.

• alloc-cortex-m (nightly-only)
• arm-dcc (Document MSRV arm-dcc#8)
• bare-metal (Document and test MSRV 1.31.0 bare-metal#31)
• cargo-binutils (Document and test MSRV 1.38.0 cargo-binutils#68)
• cortex-a (nightly-only)
• cortex-m-rt (Document MSRV in README cortex-m-rt#264)
• cortex-m-semihosting (Add MSRV 1.33.0 to CI cortex-m-semihosting#53)
• cortex-m (Add MSRV note to README cortex-m#207)
• cortex-r (Document MSRV in README and test on Rust stable cortex-ar#3)
• cross (Change CI to build with Rust 1.32 and document that as MSRV cross-rs/cross#433)
• embedded-hal (Add MSRV configuration to CI embedded-hal#198)
• fixedvec-rs (Document MSRV 1.23.0 fixedvec-rs#19)
• gpio-cdev (Add MSRV 1.34.0 gpio-cdev#32)
• gpio-utils (Document MSRV 1.26.2 gpio-utils#31)
• itm (Document MSRV on README itm#29)
• linux-embedded-hal (Update gpio-cdev and add MSRV linux-embedded-hal#42)
• msp430-rt (nightly-only)
• msp430 (nightly-only)
• mutex-trait (Document MSRV 1.31.0 on README mutex-trait#10)
• nb
• panic-itm (Add MSRV 1.31.0 to CI panic-itm#12)
• panic-semihosting (Add MSRV 1.32.0 to CI panic-semihosting#21)
• r0 (Document and test MSRV 1.31.0 r0#22)
• register-rs (no CI)
• riscv-rt (Document MSRV on README riscv-rt#50)
• riscv (Document MSRV on README riscv#40)
• rust-i2cdev (Document and test MSRV 1.32.0 rust-i2cdev#62)
• rust-spidev (already had MSRV)
• rust-sysfs-gpio (already had MSRV)
• rust-sysfs-pwm (already had MSRV)
• svd2rust (Use standard wording for the MSRV note svd2rust#436)
• svd (Document and test MSRV 1.35.0 svd#113)

[teskje]

I'd like to help out! I'll take the embedded-hal crate if nobody minds.

Edit: Oh, nvm, that already has a tested MSRV of 1.35. Can be ticked in the list.

[teskje]

Here are the others that already have a MSRV:

• rust-spidev (1.31)
• rust-sysfs-gpio (1.31)
• rust-sysfs-pwm (1.28)
• svd2rust (1.37)

[ericevenchick]

Put something together to automate this, here are my results so far

repos/alloc-cortex-m: MSRV = nightly
repos/arm-dcc: MSRV = 1.31.0
repos/bare-metal: MSRV = 1.31.0
repos/cargo-binutils: MSRV = 1.32.0
repos/cortex-a: MSRV = nightly
repos/cortex-m: MSRV = 1.31.0
repos/cortex-m-rt: MSRV = 1.31.0
repos/cortex-m-semihosting: MSRV = 1.32.0
repos/cortex-r: MSRV = 1.31.0
repos/cross: MSRV = 1.32.0
repos/embedded-hal: MSRV = 1.31.0
repos/fixedvec-rs: MSRV = 1.30.0
repos/gpio-cdev: MSRV = 1.31.0
repos/gpio-utils: MSRV = 1.30.0
repos/itm: MSRV = 1.32.0
repos/linux-embedded-hal: MSRV = 1.32.0
repos/msp430: MSRV = nightly
repos/msp430-rt: MSRV = nightly
repos/mutex-trait: MSRV = 1.31.0
repos/panic-itm: MSRV = 1.31.0
repos/panic-semihosting: MSRV = 1.32.0
repos/r0: MSRV = 1.31.0
repos/register-rs: MSRV = nightly
repos/riscv: MSRV = 1.30.0
repos/riscv-rt: MSRV = 1.31.0
repos/rust-i2cdev: MSRV = 1.31.0
repos/rust-spidev: MSRV = 1.31.0
repos/rust-sysfs-gpio: MSRV = 1.31.0
repos/rust-sysfs-pwm: MSRV = 1.30.0
repos/svd: MSRV = 1.37.0
repos/svd2rust: MSRV = 1.36.0

All of the "nightly" MSRVs are due to #![feature] being used on the stable channel.

error[E0554]: `#![feature]` may not be used on the stable release channel

I have only tested from 1.30.0 to 1.42.0.

[adamgreig]

Here are the others that already have a MSRV:

• rust-spidev (1.31)
• rust-sysfs-gpio (1.31)
• rust-sysfs-pwm (1.28)
• svd2rust (1.37)

Thanks for checking! I noticed most of those (and embedded-hal) specify the MSRV in their README instead of in the crate documentation, but I think that's just as effective. svd2rust itself doesn't actually say "MSRV" anywhere, though the README does mention it briefly. It might be worth a quick PR to just include the standard wording.

Put something together to automate this, here are my results so far

Amazing, thanks!

[teskje]

I noticed most of those (and embedded-hal) specify the MSRV in their README instead of in the crate documentation, but I think that's just as effective.

True. Would it make sense to update the "Documenting the MSRV" to mention the README instead of lib.rs, so it gets done consistently? Or alternatively, should we update those crates to list the MSRV at both places?

[nastevens]

I think it would make sense to incorporate it in both - the README is front and center on crates.io, but the top-level rustdoc is what appears on docs.rs.

[teskje]

On the other hand it appears to be common practice in Rust projects to document the MSRV in the README only. Personally I wouldn't expect it to be documented on docs.rs, that is more like a reference to me and I usually have gone through the README on GitHub or crates.io before getting there. That doesn't mean putting it into the crate module docs would hurt, although there is some added maintenance burden of one more place to be updated when the MSRV is increased.

[teskje]

cortex-m also already documents and tests its MSRV and can be ticked. Though in this case, the MSRV is documented only in the rustdoc, not the README.

[adamgreig]

I think historically a lot of rust-embedded crates had very minimal READMEs with pretty much just a link to the documentation; personally I'm all in favour of more fully-fledged READMEs alongside the docs. As @nastevens points out, the README is the first thing a user sees on crates.io and on GitHub, while the documentation is what you see once you're on docs.rs, so I think it makes perfect sense to have the MSRV in the README first and foremost.

It is a bit of a pain to have the MSRV duplicated in the README and documentation as well as the CI config file, but maybe worth it for having the MSRV clear in both locations. Anyone else have thoughts on the matter? I'm happy to update the relevant docs to say the MSRV should be documented in the README/both places.