Description

Some background

Currently, getting anything more complex than examples/rust-hello-world running is undocumented, and really hard without advanced knowledge of how the RIOT build-system works.

I personally have only limited experience with Rust, Cargo and RIOT. In the following, I will list some difficulties I encountered.

Areas that require documentation

Creating a RIOT Rust module or RIOT wrapper

• how to properly create a Rust RIOT module or extend the riot-wrappers crate

Setting up out-of-tree builds

• setting up a OOT rust-application is quite straight-forward, but some stuff is still difficult to find out
  • e.g. how to declare used modules (e.g. in Makefile, Cargo.toml)?
• setting up a Rust OOT RIOT module is unclear. Extending the module creation documentation would be helpful.

Using RIOT C-modules that are neither in riot-wrappers nor in riot-sys

• being able to access any C RIOT module is necessary for any serious project
• there is a bit of documentation in riot-sys that points out that extra headers can just be added in riot-headers.h.
• how should then riot-headers.h be extended?
  1. changing it directly in the .cargo registry works, but this is no clean solution
  2. cloning riot-wrappers and riot-sys from git, modifying them, and then pointing to them in Cargo.toml kinda works. Even if I check-out to the exact version stated in the .cargo registry, I get some warnings (e.g. gnrc_netif_dev_is_6lo redeclared with a different signature) -- this solution cannot be right either

Mismatched riot-sys exports:

• Example: both riot_sys::mutex_lock() and riot_sys::inline::mutex_lock() work with riot_sys::inline::mutex_t and will not compile when supplied with riot_sys::mutex. But using riot_sys::inline::mutex_t will then not work with e.g. riot_sys::ztimer_mutex_lock(). What is the workaround in this case?

Getting some sweet language support

• Rust is (at least for me) no language to use without proper integration in a code editor or IDE
  • rust-analyzer can be configured independent of the editor choice by setting the environment variables in .cargo/config.toml see discussion below
  • LSP support for Rust app development
  • LSP support for riot-sys in Rust module developement
• my experience with vscode: the C bindings generated by riot-sys in ./target are not seen by rust-analyzer. This perhaps boils down to the fact that this is no pure cargo build.
• would be nice to have a proper integration in at least one code editor - seems that rust-analyzer can be configured independently