From d9124b3e7110f488b5d12d5bd019cb8d0e212af0 Mon Sep 17 00:00:00 2001
From: David Brown <david.brown@linaro.org>
Date: Tue, 25 Feb 2025 11:19:01 -0700
Subject: [PATCH] docs: develop: languages: Add initial documentation for Rust

Start a simple set of documentation on using Rust within Zephyr.  This
gives an overview of how to use Rust, and pointers to the generated API
documentation.

Signed-off-by: David Brown <david.brown@linaro.org>
---
 doc/develop/languages/index.rst      |  1 +
 doc/develop/languages/rust/index.rst | 91 ++++++++++++++++++++++++++++
 2 files changed, 92 insertions(+)
 create mode 100644 doc/develop/languages/rust/index.rst

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..b2699710cc25
--- /dev/null
+++ b/doc/develop/languages/rust/index.rst
@@ -0,0 +1,91 @@
+.. _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:: console
+
+       west config manifest.project-filter +zephyr-lang-rust
+       west sync
+
+    This should cause the Rust language support to be placed in ``modules/lang/rust``.
+
+2.  Enable Rust support, via :kconfig:option:`CONFIG_RUST` in the ``prj.conf``.  The easiest way to do
+    this, and the Cmake part is to start with one of the samples in ``modules/lang/rust/samples``.
+
+3.  Configure the application's ``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 ``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 ``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:: console
+
+   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.