diff --git a/doc/develop/languages/index.rst b/doc/develop/languages/index.rst index 033b9084ac4f..b1b54355f1a4 100644 --- a/doc/develop/languages/index.rst +++ b/doc/develop/languages/index.rst @@ -8,3 +8,4 @@ Language Support c/index.rst cpp/index.rst + rust/index.rst diff --git a/doc/develop/languages/rust/index.rst b/doc/develop/languages/rust/index.rst new file mode 100644 index 000000000000..f84f2f3dfd37 --- /dev/null +++ b/doc/develop/languages/rust/index.rst @@ -0,0 +1,100 @@ +.. _language_rust: + +Rust Language Support +##################### + +Rust is a modern systems programming language designed to provide memory safety, concurrency, and +performance without sacrificing low-level control. It achieves this through a unique ownership model +that eliminates common bugs like null pointer dereferencing and data races at compile time. + +Rust's emphasis on safety and correctness makes it particularly well-suited for embedded systems and +environments where reliability is critical. +Additionally, Rust offers powerful abstractions without a runtime or garbage collector, allowing +developers to write both high-level code and low-level hardware interactions with confidence and +efficiency. + +These attributes make Rust a strong choice for projects on Zephyr, where resource constraints and +system stability are paramount. + +Enabling Rust Support +********************* + +In order to enable Rust support in a Zephyr application, a few things need to be done: + +1. As Rust is currently an optional module, the module needs to be enabled. The easiest way to do + this is with west: + + .. code-block:: shell + + west config manifest.project-filter +zephyr-lang-rust + west update + + This should cause the Rust language support to be placed in :samp:`modules/lang/rust` in your + Zephyr workspace. + +2. Enable Rust support, via :kconfig:option:`CONFIG_RUST` in the :file:`prj.conf`. The easiest way + to do this (as well as the CMake setup from the next step) is to start with one of the samples + in :module_file:`modules/lang/rust/samples `. + +3. Configure the application's :file:`CMakeLists.txt` file to support CMake. Again this is easiest + to copy from a sample, but this will look something like: + + .. code-block:: cmake + + cmake_minimum_required(VERSION 3.20.0) + + find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) + + project(my_app) + rust_cargo_application() + +4. Create a :file:`Cargo.toml` that describes how to build the Rust application. From the Hello + World sample: + + .. code-block:: toml + + [package] + # This must be rustapp for now. + name = "rustapp" + version = "0.1.0" + edition = "2021" + description = "The description of my app" + license = "Apache-2.0 or MIT" + + [lib] + crate-type = ["staticlib"] + + [dependencies] + zephyr = "0.1.0" + log = "0.4.22" + + The only required dependency is ``zephyr`` which provides the zephyr crate that is used to + interface with Zephyr. + +5. Build as you would any other Zephyr application. Only a few targets currently support Rust + (these can be seen in the + :module_file:`modules/lang/rust/etc/platforms.txt ` file). + +API Documentation +***************** + +The `API Documentation`_ for the latest version in the module is kept on gh-pages. + +.. _`API Documentation`: + https://zephyrproject-rtos.github.io/zephyr-lang-rust/nostd/zephyr/index.html + +This documentation is generated for a general target, with all features enabled. Once you have an +application that is buildable, you can generate documentation specifically for your target: + +.. code-block:: shell + + west build -t rustdoc + + ... + + Generated /my/path/app/zephyr/build/doc/rust/target/riscv32i-unknown-none-elf/doc/rustapp/index.html + +The path printed at the end can be opened in a browser. This top level docs will be for your +application itself. Look for the 'zephyr' crate on the left side bar, and this will take you to the +docs for Zephyr. This page will also generate local docs for any dependencies used by your +application, directly or indirectly.