1.. _language_rust:
2
3Rust Language Support
4#####################
5
6Rust is a modern systems programming language designed to provide memory safety, concurrency, and
7performance without sacrificing low-level control. It achieves this through a unique ownership model
8that eliminates common bugs like null pointer dereferencing and data races at compile time.
9
10Rust's emphasis on safety and correctness makes it particularly well-suited for embedded systems and
11environments where reliability is critical.
12Additionally, Rust offers powerful abstractions without a runtime or garbage collector, allowing
13developers to write both high-level code and low-level hardware interactions with confidence and
14efficiency.
15
16These attributes make Rust a strong choice for projects on Zephyr, where resource constraints and
17system stability are paramount.
18
19Enabling Rust Support
20*********************
21
22In order to enable Rust support in a Zephyr application, a few things need to be done:
23
241.  As Rust is currently an optional module, the module needs to be enabled.  The easiest way to do
25    this is with west:
26
27    .. code-block:: shell
28
29       west config manifest.project-filter +zephyr-lang-rust
30       west update
31
32    This should cause the Rust language support to be placed in :samp:`modules/lang/rust` in your
33    Zephyr workspace.
34
352.  Enable Rust support, via :kconfig:option:`CONFIG_RUST` in the :file:`prj.conf`. The easiest way
36    to do this (as well as the CMake setup from the next step) is to start with one of the samples
37    in :module_file:`modules/lang/rust/samples <zephyr-lang-rust:samples>`.
38
393.  Configure the application's :file:`CMakeLists.txt` file to support Rust.  Again this is easiest
40    to copy from a sample, but this will look something like:
41
42    .. code-block:: cmake
43
44       cmake_minimum_required(VERSION 3.20.0)
45
46       find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
47
48       project(my_app)
49       rust_cargo_application()
50
514.  Create a :file:`Cargo.toml` that describes how to build the Rust application. From the Hello
52    World sample:
53
54    .. code-block:: toml
55
56       [package]
57       # This must be rustapp for now.
58       name = "rustapp"
59       version = "0.1.0"
60       edition = "2021"
61       description = "The description of my app"
62       license = "Apache-2.0 or MIT"
63
64       [lib]
65       crate-type = ["staticlib"]
66
67       [dependencies]
68       zephyr = "0.1.0"
69       log = "0.4.22"
70
71    The only required dependency is ``zephyr`` which provides the zephyr crate that is used to
72    interface with Zephyr.
73
745.  Build as you would any other Zephyr application.  Only a few targets currently support Rust
75    (these can be seen in the
76    :module_file:`modules/lang/rust/etc/platforms.txt <zephyr-lang-rust:etc/platforms.txt>` file).
77
78API Documentation
79*****************
80
81The `API Documentation`_ for the latest version in the module is kept on gh-pages.
82
83.. _`API Documentation`:
84   https://zephyrproject-rtos.github.io/zephyr-lang-rust/nostd/zephyr/index.html
85
86This documentation is generated for a general target, with all features enabled.  Once you have an
87application that is buildable, you can generate documentation specifically for your target:
88
89.. code-block:: shell
90
91   west build -t rustdoc
92
93   ...
94
95   Generated /my/path/app/zephyr/build/doc/rust/target/riscv32i-unknown-none-elf/doc/rustapp/index.html
96
97The path printed at the end can be opened in a browser.  This top level docs will be for your
98application itself.  Look for the 'zephyr' crate on the left side bar, and this will take you to the
99docs for Zephyr.  This page will also generate local docs for any dependencies used by your
100application, directly or indirectly.
101