zephyr_add_rust_library

This repo contains

• the CMake function zephyr_add_rust_library used for adding Rust library crate dependencies to Zephyr apps. This funcition is defined in zephyr_add_rust_library.cmake.
• a minimal Zephyr test app

Using zephyr_add_rust_library has the following benefits:

• crates are automatically compiled to static libraries as part of the Zephyr build process
• adding and removing Rust dependencies is easy
• debugging works seamlessly
• Rust build artefacts are output to the Zephyr build folder

⚠️ The code in this repo should be considered work in progress. If you run into any issues, please consider reporting them or submitting a PR!

Prerequisites

The reader is assumed to be familiar with the basics of no_std Rust and how to call Rust code from C.

Usage

First, make sure you have installed Rust. Then put zephyr_add_rust_library.cmake in the same directory as your CMakeLists.txt. To add a dependency on a library crate named my-lib-crate, add these lines to your CMakeLists.txt:

# Import the zephyr_add_rust_library function
include(zephyr_add_rust_library.cmake)

# Add my-lib-crate crate dependency.
zephyr_add_rust_library(
  CRATE_NAME my-lib-crate # Crate name as specified in Cargo.toml
  CRATE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/my-lib-crate # Crate root dir
  CRATE_HEADER_DIR ${CMAKE_CURRENT_SOURCE_DIR}/my-lib-crate/include # C header dir
)

${CMAKE_CURRENT_SOURCE_DIR} is the directory containing your CMakeLists.txt. For additional arguments and more detailed documentation, see zephyr_add_rust_library.cmake.

Errors along the lines of Could not find specification for target ... indicate that you need to add a Rust target corresponding to the architechure you're building for. To do this, run rustup target add [target], where [target] is the name of the target in the error message (a complete list of targets can be found here).

Known issues and future work

zephyr_add_rust_library.cmake should be considered work in progress and has so far been tested on macOS using the ninja generator to build for nRF52/nRF53 SOCs with Cortex M4/M33 architectures. Known issues include:

• Limited cargo target selection - zephyr_add_rust_library uses KConfig variables like CONFIG_FPU, CONFIG_CPU_CORTEX_M4 etc to set a suitable cargo target. This mapping is not complete and only supports some Cortex M architectures at the time of writing.
• Ignored duplicate symbols - Library crate dependencies are linked using --allow-multiple-definition to silence errors when when linking multiple libraries containing the same compiler builtins. Unfortunately, this means that legitimate multiple definition errors will also go unnoticed and it's up to the user to detect these.