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