How zephyrproject-rtos/zephyr-lang-rust works
Project type and purpose
• This project is not a single application but a *tooling and library suite* that adds Rust language support to Zephyr.
• It includes:
– Core Rust API bindings to Zephyr (zephyr, zephyr-sys)
– Procedural macros (zephyr-macros)
– Build-time code generators (zephyr-build, docgen)
– CMake/C code glue (main.c, CMakeLists.txt)
– Sample Rust applications under samples/
– Test harnesses under tests/
File structure
• Top‐level build/config files:
– CMakeLists.txt + Kconfig
– main.c (C entry point calling into Rust)
– .github/workflows for CI
• Crates (Rust libraries and tools):
– /zephyr : high‐level Rust API crate
– /zephyr-sys : raw FFI bindings & wrapper.h
– /zephyr-macros : procedural macros (e.g., #[task])
– /zephyr-build : build‐script crate (exports Kconfig & parses devicetree)
– /docgen : generates API docs from Zephyr DTS/Kconfig metadata
• Samples & tests:
– samples/* : example Rust applications (Cargo.toml + prj.conf + src/)
– tests/* : driver and timing tests
• Build integration:
– The CMake function rust_cargo_application() ties CMake to Cargo.
– Build‐script (build.rs) in each Rust app uses zephyr-build to export Kconfig symbols.
Extract additional insights from README
• To enable Rust, the user selects CONFIG_RUST in Zephyr’s Kconfig.
• The Rust toolchain (via rustup) must install no-std targets.
• Cargo is invoked by the Zephyr build system, producing a staticlib.
• The generated Rust static library is linked into Zephyr’s final firmware.
Main components and interactions
a. Components:
1. Zephyr Build System (CMake + Kconfig + west)
2. Rust Toolchain (rustup + cargo)
3. zephyr-build crate (build.rs)
4. zephyr-sys crate (FFI wrappers)
5. zephyr-macros crate (proc‐macros)
6. zephyr crate (Rust API)
7. Documentation generator (docgen)
8. Sample/Test projects
9. Final firmware linker (ld)
b. Relationships & data flows:
• Zephyr Build System → invokes → Cargo (via rust_cargo_application)
• Cargo → runs → zephyr-build build.rs → reads Kconfig & Devicetree → emits Rust cfg symbols
• Cargo → compiles → zephyr-sys (generates FFI via wrapper.h)
• Cargo → applies → zephyr-macros at compile time
• Cargo → compiles → zephyr crate + application code → staticlib
• CMake → links → Rust staticlib + Zephyr kernel → firmware
• docgen → parses → Zephyr metadata → renders docs in /docs
c. Architectural patterns:
– Build‐time code generation (build.rs + devicetree parser)
– FFI boundary encapsulation (zephyr-sys)
– Procedural macro expansion (zephyr-macros)
– C/Rust interoperability via static libraries
d. Key technologies:
– CMake + Kconfig (Zephyr build)
– rustup + Cargo (Rust toolchain)
– pest (for parsing DTS in zephyr-build)
– serde/yaml (for sample/test YAML files)
– docgen (Rust/Cargo + CMake)
Essential elements to capture
– CMake + Kconfig as the orchestrator.
– Cargo build pipeline with build.rs (zephyr-build).
– FFI binding generation (zephyr-sys ➔ wrapper.h).
– Macro expansion (zephyr-macros).
– Static linking into Zephyr firmware.
– Documentation generation path (docgen).
– Sample/test projects as consumers.