Rust Standards & Tips

Owned by Jack Rubacha
Last updated: Nov 11, 2024
3 min read

We use rust for a few projects right now, including both well supported Odyssey projects and lesser used experimental firmware projects. This page is split into 3 sections → general notes, linux/multithreaded notes, and firmware notes. Make sure to read the applicable sections before developing in rust at NER.

 

IDE Setup

Use rust-analyzer extension and you should be all set for both embedded and applications context.

Helpful cargo commands

  • cargo run to test your code

  • cargo run --release to test your code’s performance

  • cargo clippy to check your code passes linter

  • cargo fmt to format your code

  • cargo test to use your tests on the code

General Notes

  • Do not use (import) modules in lib.rs!! This could global import things. Instead use full paths.

  • Use Result and Option. These structs are not just for libraries, use them for your own return results.

    • Use Result for things that could return an error object.

    • Use Option for things that could return null or may not “find” anything.

  • NEVER unwrap. Alternatives

    • expect if an error is a critical failure and rare

    • unwrap_or_default if you do not care about the value and will no-op if the value is empty, 0, etc.

    • match the some/none or ok/err if you need to transform the error and/or break out/return from a function

    • unwrap_or_else if you need to provide a default value and want to perform other operations

    • unwrap_or to provide a const-context default

  • For functions with alot of parameters, use an options struct and pass that struct in.

  • For struct initialization, use a new function which returns Self

  • Printing

    • Debug print something (implement with derive(Debug) on the struct): {:?}

    • Display value of something (implement with derive(Display) on the struct): {}

  • If you use a library, do not use its dependencies directly. Instead add them to Cargo.toml.

    • Example: dont use prisma_client_rust::chrono , instead use chrono as then if you remove prisma_client_rust chrono will still work

  •  

Applications notes

Entrypoint/settings

  • Use clap and clap_derive for all settings that should be changed at runtime. As rust is a compiled language, making a setting that may require changing involves rebuiliding and deploying a sometimes hefty application. Use clap_derive (as seen here) to expose your setting to the program. Use the environment variables as the example shows

  • Dockerization should use environment variables for all settings (see above)

Tokio/Threading

  • Use threads conservatively. If you need two+ things to happen on a loop, use a tokio::select in order to time multiple things that require access to the same variables.

  • Use print levels (trace, debug, info, warn) when you want a print to be included in the final product

 

Firmware notes

  • Use the embassy version of stuff. Embassy provides alternatives of normal functions for most stuff, use them. Do not consider adding a new library unless you are sure an embassy proejct doesn’t already include it.

  • Do all initialization of hardware using the peripherals variable in main.rs , and then once a new object is procured initialize that in the task.

  • Ensure you arent copying things into functions. Make their context static or give a lifetime, do not copy a variable, especially a String.

  • Use DMA/await when possible. No matter how much work, avoid the xxx_blocking function available, use the await async functions. This allows better parallelism within code leading to optimal performance.