From fdd178ec2b5a364a9604e1a3992b6ebd79c960dc Mon Sep 17 00:00:00 2001 From: David Brown Date: Wed, 8 Jan 2025 14:33:01 -0700 Subject: [PATCH 1/3] doc: develop: languages: rust: Create basic Rust doc Create an initial document describing how to get started a Rust application on Zephyr. Signed-off-by: David Brown --- doc/develop/languages/index.rst | 1 + doc/develop/languages/rust/index.rst | 88 ++++++++++++++++++++++++++++ 2 files changed, 89 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..2481277dd103 --- /dev/null +++ b/doc/develop/languages/rust/index.rst @@ -0,0 +1,88 @@ +.. _language_rust: + +Rust Language Support +##################### + +Rust is a modern systems programming language focused on safety, speed, and concurrency. Unlike +traditional systems programming languages such as C and C++, Rust ensures memory safety without +relying on garbage colleciton, thanks to its ownership model and borrow checker. Rust also offers a +rich type system, expressive syntax, and support for zero-cost abstractions, making it well-suited +for embedded development. + +Rust’s emphasis on reliability and performance aligns well with Zephyr. By combining Rust’s +guarantees with Zephyr’s robust ecosystem, developers can create efficient and maintainable embedded +applications. The integration of Rust with Zephyr allows developers to leverage Rust’s language +features while benefiting from Zephyr’s drivers, APIs, and multi-threading capabilities. + +At this point, Rust support in Zephyr is entirely for those wishing to write applications in Rust +that run *on* Zephyr. Any efforts to add code *to* Zephyr, written in Rust (such as device drivers) +would be an independent effort. + +Enabling Rust Support +********************* + +Both Rust and Zephyr have their own build systems, along with an ecosystem around this. For Rust, +this is the "crate" system of managing external dependencies. Because this support is for +applications written in Rust, Zephyr's rust support leverages crates, and the cargo tool to build +the Rust part of the application. + +Enabling the module +------------------- + +Before getting very far, it is important to make sure that the Rust support module is included. By +default, rust support is listed in the project manifest, but is marked as optional. It is easy to +enable the module using ``west``: + +.. code-block:: console + + west config manifest.project-filter +zephyr-lang-rust + west update + +This should enable the module, and then sync modules, which will add the module to your modules +directory. + +Setting up the environment +-------------------------- + +Before starting with Rust, make sure you are able to build a simple Zephyr application, such as +"blinky". It is easier to debug Zephyr build issues before introducing Rust. + +After this, you will need to have a recent Rust toolchain install, as well as target support for +your desired target. It is generally easiest to use `Rustup`_ to install an maintain a rust +installation. After following these instructions, you will need to install target support for your +target. + +Because Zephyr and LLVM use different naming conventions for targets, and can be a little +challenging to determine the right target to install. Sometimes, it is easiest to proceed with +building a Rust sample with your desired target, and the toolchain will emit an error message giving +the appropriate command to run. The target needed will depend both on the board/soc selected, as +well as certain configuration choices (such as whether floating point is enabled). Please see the +function ``_rust_map_target`` in :module_file:`zephyr-lang-rust:CMakeLists.txt` for details on how +this is computed. As an example, a particular Cortex-M target may need the following command: + +.. code-block:: console + + rustup target add thumbv7m-none-eabi + +.. _`Rustup`: https://rustup.rs/ + +Building a sample +----------------- + +.. This file (a directory in samples) and the above CMakeLists.txt should be done with the + module_file reference. However, the current doc build doesn't seem to be including modules, so + for now, just make these regular file references. + +The directory :file:`zephyr-lang-rust:samples` contains some samples that can be useful for +testing. Hello world is a good basic test, although blinky may also be useful if your target has an +LED defined. Please make sure that :file:`samples/basic/blink` works with your board, +however, before trying it with Rust. + +Following from the getting-started guide, you can build the hello world sample in rust with: + +.. code-block: console + + cd ~/zephyrproject/modules/lang/rust + west build -p always -b samples/blinky + +Provided this is successful, the image can be flashed and tested as per the getting started guide. From a5451e38c857fc05fc16b6040804d8d0586dbe5f Mon Sep 17 00:00:00 2001 From: David Brown Date: Mon, 13 Jan 2025 13:56:47 -0700 Subject: [PATCH 2/3] CI: doc-build: Build the Rust documentation This adds a job that builds the rustdoc documentation. Signed-off-by: David Brown --- .github/workflows/doc-build.yml | 81 +++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 69c7b787c457..ce0781e6471a 100644 --- a/.github/workflows/doc-build.yml +++ b/.github/workflows/doc-build.yml @@ -51,6 +51,7 @@ jobs: tests/ **/Kconfig* west.yml + submanifests/optional.yaml scripts/dts/ doc/requirements.txt .github/workflows/doc-build.yml @@ -255,6 +256,85 @@ jobs: doc/_build/latex/zephyr.pdf doc/_build/latex/zephyr.log + rust-doc-build-html: + name: "Rust Documentation Build (HTML)" + needs: [doc-file-check] + if: > + github.repository_owner == 'zephyrproject-rtos' && + ( needs.doc-file-check.outputs.file_check == 'true' || github.event_name != 'pull_request' ) + runs-on: ubuntu-22.04 + + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + path: zephyr + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.11 + + - name: Setup Zephyr Project + uses: zephyrproject-rtos/action-zephyr-setup@v1 + with: + app-path: zephyr + manifest-file-name: west.yml + toolchains: arm-zephyr-eabi + + - name: Bring in docs + shell: bash + run: | + set -x + cd zephyr + # Show a git log to make sure we got the upstream version and west didn't "fix" it for us. + git log -3 + + # Add the rust module to the manifest. + west config manifest.project-filter +zephyr-lang-rust + west update zephyr-lang-rust + + echo Rust support + ls -l ../modules/lang/rust + + - name: Install Rust Target + shell: bash + run: | + rustup target add thumbv7em-none-eabi + rustup target add thumbv7m-none-eabi + + - name: Build Rust docs + shell: bash + run: | + cargo --version + cd zephyr + west build -t rustdoc -b nrf52840dk/nrf52840 ../modules/lang/rust/docgen + cd .. + mkdir rustdocs + mv zephyr/build/rust/target/thumbv7em-none-eabi/doc rustdocs/nostd + cp modules/lang/rust/docs/top-index.html rustdocs/index.html + + # TODO: Build the std-based docs as well + - name: Build Rust Build-time docs + shell: bash + run: | + cd modules/lang/rust/zephyr-build + cargo doc + mv target/doc ../../../../rustdocs/std + + cd ../../../.. + du -hs rustdocs + ls -l rustdocs + + - name: compress-rust-docs + run: | + tar --use-compress-program="xz -T0" -cf rustdocs-output.tar.xz rustdocs + + - name: Upload docs artifact + uses: actions/upload-artifact@v4 + with: + name: rustdocs + path: rustdocs-output.tar.xz + doc-build-status-check: if: always() name: "Documentation Build Status" @@ -262,6 +342,7 @@ jobs: - doc-build-pdf - doc-file-check - doc-build-html + - rust-doc-build-html uses: ./.github/workflows/ready-to-merge.yml with: needs_context: ${{ toJson(needs) }} From 441200dfa58be8540d0cdd1dae4e14851b981c31 Mon Sep 17 00:00:00 2001 From: David Brown Date: Fri, 24 Jan 2025 15:39:18 -0700 Subject: [PATCH 3/3] CI: Publish Rust docs if they were generated Include the generated Rust documentation in the published docs, both for PR and for main, if they were generated. Signed-off-by: David Brown --- .github/workflows/doc-publish-pr.yml | 8 ++++++++ .github/workflows/doc-publish.yml | 6 ++++++ 2 files changed, 14 insertions(+) diff --git a/.github/workflows/doc-publish-pr.yml b/.github/workflows/doc-publish-pr.yml index 786bd14aed27..ecb547b6f565 100644 --- a/.github/workflows/doc-publish-pr.yml +++ b/.github/workflows/doc-publish-pr.yml @@ -60,6 +60,9 @@ jobs: if [ -f api-coverage/api-coverage.tar.xz ]; then tar xf api-coverage/api-coverage.tar.xz -C api-coverage fi + if [ -f rustdocs/rustdocs-output.tar.xz ]; then + tar xf rustdocs/rustdocs-output.tar.xz -C rustdocs + fi - name: Configure AWS Credentials if: steps.download-artifacts.outputs.found_artifact == 'true' @@ -82,3 +85,8 @@ jobs: s3://builds.zephyrproject.org/${{ github.event.repository.name }}/pr/${PR_NUM}/api-coverage \ --delete fi + if [ -d rustdocs/rustdocs ]; then + aws s3 sync --quiet rustdocs/rustdocs/ \ + s3://builds.zephyrproject.org/${{ github.event.repository.name }}/pr/${PR_NUM}/rustdocs \ + --delete + fi diff --git a/.github/workflows/doc-publish.yml b/.github/workflows/doc-publish.yml index 51c451c75ea3..7731baa687d0 100644 --- a/.github/workflows/doc-publish.yml +++ b/.github/workflows/doc-publish.yml @@ -35,6 +35,9 @@ jobs: if [ -f api-coverage/api-coverage.tar.xz ]; then tar xf api-coverage/api-coverage.tar.xz -C api-coverage fi + if [ -f rustdocs/rustdocs-output.tar.xz ]; then + tar xf rustdocs/rustdocs-output.tar.xz -C rustdocs + fi - name: Configure AWS Credentials uses: aws-actions/configure-aws-credentials@v4 @@ -58,4 +61,7 @@ jobs: if [ -d api-coverage/coverage-report ]; then aws s3 sync --quiet api-coverage/coverage-report/ s3://docs.zephyrproject.org/api-coverage/${VERSION} --delete fi + if [ -d rustdocs/rustdocs ]; then + aws s3 sync --quiet rustdocs/rustdocs/ s3://docs.zephyrproject.org/rustdocs/${VERSION} --delete + fi aws s3 cp --quiet pdf-output/zephyr.pdf s3://docs.zephyrproject.org/${VERSION}/zephyr.pdf