diff --git a/doc/doxygen/src/using-rust.md b/doc/doxygen/src/using-rust.md index c0b157d0757e..3670abadcc74 100644 --- a/doc/doxygen/src/using-rust.md +++ b/doc/doxygen/src/using-rust.md @@ -84,31 +84,26 @@ Toolchain {#toolchain} To install the necessary Rust components, it is easiest use [**rustup**, installed as described on its website]. -Using most of Rust on RIOT requires a nightly version of Rust, -because some transpiled expressions for RIOT make use of unstable features, -and because the RIOT wrappers use some unstable idioms. +Using Rust on RIOT needs the latest stable or nightly version of Rust, +depending on the precise example used. +(Several modules, such as CoAP, SAUL or the shell, need features not yet available on stable yet; +the minimal test is performed on stable, and examples are configured to use stable as it becomes available). -@note -Building on stable is supported for some examples and platforms starting with Rust 1.59 -(e.g., the rust-hello-world on any ARM Cortex, but not yet on native). -Try it out by adding `CARGO_CHANNEL=stable` to the project's Makefile; -where it doesn't work, rustc will complain that "`#![feature]` may not be used on the stable release channel". - -@note -A stable version of Rust is not currently provided with the Docker images; -consequently, builds on stable are not tested as regularly as builds on nightly. - -Make sure you have both the nightly **toolchain** +Make sure you have both the nightly and stable **toolchains** and the core library for the CPU (**target**) of your choice available: ``` $ rustup toolchain add nightly +$ rustup toolchain add stable $ rustup target add thumbv7m-none-eabi --toolchain nightly +$ rustup target add thumbv7m-none-eabi --toolchain stable ``` -(Substitute thumbv7m-none-eavi with the value of `RUST_TARGET` +Substitute thumbv7m-none-eabi with the value of `RUST_TARGET` in the output of `make info-build` of an application that has your current board selected, or just add it later whenever the Rust compiler complains about not finding the core library for a given target). +Installing only nightly will work just as well, +but you may need to remove the `CARGO_CHANNEL = stable` lines from tests or examples. While Rust comes with its own [cargo] dependency tracker for any Rust code, diff --git a/tests/rust_minimal/Cargo.toml b/tests/rust_minimal/Cargo.toml index 739e38879b6c..128a03eb9f48 100644 --- a/tests/rust_minimal/Cargo.toml +++ b/tests/rust_minimal/Cargo.toml @@ -8,6 +8,12 @@ resolver = "2" [lib] crate-type = ["staticlib"] +[profile.release] +# Setting the panic mode has little effect on the built code (as Rust on RIOT +# supports no unwinding), but setting it allows builds on native without using +# the nightly-only lang_items feature. +panic = "abort" + [dependencies] # `default-features = false` can be removed with 0.8, and enables building on stable during the 0.7 series riot-wrappers = { version = "0.7", features = [ "set_panic_handler" ], default-features = false } diff --git a/tests/rust_minimal/Makefile b/tests/rust_minimal/Makefile index 9001f83c6c9b..0f91d760bed5 100644 --- a/tests/rust_minimal/Makefile +++ b/tests/rust_minimal/Makefile @@ -5,6 +5,11 @@ BASELIBS += $(APPLICATION_RUST_MODULE).module FEATURES_REQUIRED += rust_target +# This example can, on all platforms, be built with a stable version of Rust. +# For most advanced features (eg. when using CoAP, SAUL or the shell with +# Rust), this needs to be set to "nightly" for the time being. +CARGO_CHANNEL = stable + # Currently unknown, something related to the LED_PORT definition that doesn't # pass C2Rust's transpilation BOARD_BLACKLIST := ek-lm4f120xl