1.. _module-pw_rust: 2 3======= 4pw_rust 5======= 6.. pigweed-module:: 7 :name: pw_rust 8 9Rust support in pigweed is **highly** experimental. Currently functionality 10is split between Bazel and GN support. 11 12----- 13Bazel 14----- 15Bazel support is based on `rules_rust <https://github.com/bazelbuild/rules_rust>`_ 16and supports a rich set of targets for both host and target builds. 17 18Building and Running the Embedded Examples 19========================================== 20The examples can be built for both the ``lm3s6965evb`` and ``microbit`` 21QEMU machines. The examples can be built and run using the following commands 22where ``PLATFORM`` is one of ``lm3s6965evb`` or ``microbit``. 23 24embedded_hello 25-------------- 26.. code-block:: bash 27 28 $ bazel build //pw_rust/examples/embedded_hello:hello \ 29 --platforms //pw_build/platforms:${PLATFORM} 30 31 $ qemu-system-arm \ 32 -machine ${PLATFORM} \ 33 -nographic \ 34 -semihosting-config enable=on,target=native \ 35 -kernel ./bazel-bin/pw_rust/examples/embedded_hello/hello 36 Hello, Pigweed! 37 38 39tokenized_logging 40----------------- 41.. code-block:: bash 42 43 $ bazel build //pw_rust/examples/tokenized_logging:tokenized_logging \ 44 --//pw_log/rust:pw_log_backend=//pw_rust/examples/tokenized_logging:pw_log_backend\ 45 --platforms //pw_build/platforms:${PLATFORM} 46 47 $ qemu-system-arm \ 48 -machine ${PLATFORM} \ 49 -nographic \ 50 -semihosting-config enable=on,target=native \ 51 -kernel ./bazel-bin/pw_rust/examples/tokenized_logging/tokenized_logging \ 52 | python -m pw_tokenizer.detokenize \ 53 base64 \ 54 ./bazel-bin/pw_rust/examples/tokenized_logging/tokenized_logging 55 56-- 57GN 58-- 59In GN, currently only building a single host binary using the standard 60libraries is supported. Windows builds are currently unsupported. 61 62Building 63======== 64To build the sample rust targets, you need to enable 65``pw_rust_ENABLE_EXPERIMENTAL_BUILD``: 66 67.. code-block:: bash 68 69 $ gn gen out --args="pw_rust_ENABLE_EXPERIMENTAL_BUILD=true" 70 71Once that is set, you can build and run the ``hello`` example: 72 73.. code-block:: bash 74 75 $ ninja -C out host_clang_debug/obj/pw_rust/examples/basic_executable/bin/hello 76 $ ./out/host_clang_debug/obj/pw_rust/examples/basic_executable/bin/hello 77 Hello, Pigweed! 78 79no_std 80------ 81Set ``pw_rust_USE_STD = false`` in the toolchain configuration, if the target 82toolchain does not support ``std``. 83 84``no_std`` toolchain builds target 85``//pw_rust/examples/basic_executable/bin/hello_pw_log``. It also prints 86"Hello, Pigweed!", but links and uses ``pw_log`` C++ backend. 87 88------------------ 89Third Party Crates 90------------------ 91Thrid party crates are vendored in the 92`third_party/rust_crates <https://pigweed.googlesource.com/third_party/rust_crates>`_ 93respository. Currently referencing these is only supported through the bazel 94build. 95