# zephyrproject-rtos/zephyr-lang-rust architecture

> Architecture diagram of the GitHub repository zephyrproject-rtos/zephyr-lang-rust, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zephyrproject-rtos/zephyr-lang-rust
- Repository: https://github.com/zephyrproject-rtos/zephyr-lang-rust

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Zephyr Build System"
        Zephyr_CMake["CMakeLists.txt"]:::blue
        Kconfig["Kconfig"]:::blue
        GH[".github/workflows/build.yml"]:::blue
    end

    subgraph "Rust Toolchain"
        Rustup["rustup toolchain"]:::blue
        Cargo["Cargo"]:::blue
    end

    subgraph "Build-time Codegen"
        ZB["zephyr-build build.rs"]:::orange
        ZM["zephyr-macros"]:::orange
    end

    subgraph "Runtime Crates"
        ZS["zephyr-sys crate"]:::green
        ZAPI["zephyr crate"]:::green
    end

    StaticLib["Rust staticlib (.a)"]:::green
    Firmware["Zephyr Firmware"]:::green

    subgraph "Documentation"
        Docp["docgen"]:::orange
    end

    subgraph "Samples & Tests"
        Samples["samples/*"]:::gray
        Tests["tests/*"]:::gray
    end

    West["west CLI"]:::blue

    %% Build orchestration
    West -->|"orchestrates build"| Zephyr_CMake
    Zephyr_CMake -->|"invokes rust_cargo_application()"| Cargo
    Rustup -->|"provides toolchain"| Cargo

    %% Cargo pipeline
    Cargo -->|"runs build.rs"| ZB
    ZB -->|"reads Kconfig & Devicetree"| Kconfig
    ZB -->|"emits Rust cfg symbols"| Cargo

    Cargo -->|"compiles FFI & generates wrapper.h"| ZS
    Cargo -->|"applies macros"| ZM
    Cargo -->|"compiles API and app code"| ZAPI
    ZAPI -->|"provides high-level API"| Cargo

    Cargo -->|"produces"| StaticLib

    %% Linking
    Zephyr_CMake -->|"links kernel + staticlib"| Firmware
    StaticLib -->|"linked into"| Firmware

    %% Documentation
    Docp -->|"parses metadata"| Kconfig
    Docp -->|"renders docs to /docs"| Docp

    %% Samples & Tests
    Samples -->|"use crates via Cargo"| Cargo
    Tests -->|"use crates via Cargo"| Cargo

    %% Click events
    click Zephyr_CMake "https://github.com/zephyrproject-rtos/zephyr-lang-rust/blob/main/CMakeLists.txt"
    click Kconfig "https://github.com/zephyrproject-rtos/zephyr-lang-rust/tree/main/Kconfig"
    click GH "https://github.com/zephyrproject-rtos/zephyr-lang-rust/blob/main/.github/workflows/build.yml"
    click ZB "https://github.com/zephyrproject-rtos/zephyr-lang-rust/blob/main/zephyr-build/src/lib.rs"
    click ZM "https://github.com/zephyrproject-rtos/zephyr-lang-rust/blob/main/zephyr-macros/src/lib.rs"
    click ZS "https://github.com/zephyrproject-rtos/zephyr-lang-rust/blob/main/zephyr-sys/Cargo.toml"
    click ZAPI "https://github.com/zephyrproject-rtos/zephyr-lang-rust/blob/main/zephyr/Cargo.toml"
    click Docp "https://github.com/zephyrproject-rtos/zephyr-lang-rust/blob/main/docgen/Cargo.toml"

    %% Styles
    classDef blue fill:#D0E6FF,stroke:#0066CC,color:#000
    classDef orange fill:#FFE6B2,stroke:#CC8400,color:#000
    classDef green fill:#D6F5D6,stroke:#339933,color:#000
    classDef gray fill:#F0F0F0,stroke:#999,color:#000
```
