1.. SPDX-License-Identifier: GPL-2.0 2 3Quick Start 4=========== 5 6This document describes how to get started with kernel development in Rust. 7 8 9Requirements: Building 10---------------------- 11 12This section explains how to fetch the tools needed for building. 13 14Some of these requirements might be available from Linux distributions 15under names like ``rustc``, ``rust-src``, ``rust-bindgen``, etc. However, 16at the time of writing, they are likely not to be recent enough unless 17the distribution tracks the latest releases. 18 19To easily check whether the requirements are met, the following target 20can be used:: 21 22 make LLVM=1 rustavailable 23 24This triggers the same logic used by Kconfig to determine whether 25``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not 26if that is the case. 27 28 29rustc 30***** 31 32A particular version of the Rust compiler is required. Newer versions may or 33may not work because, for the moment, the kernel depends on some unstable 34Rust features. 35 36If ``rustup`` is being used, enter the checked out source code directory 37and run:: 38 39 rustup override set $(scripts/min-tool-version.sh rustc) 40 41This will configure your working directory to use the correct version of 42``rustc`` without affecting your default toolchain. If you are not using 43``rustup``, fetch a standalone installer from: 44 45 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone 46 47 48Rust standard library source 49**************************** 50 51The Rust standard library source is required because the build system will 52cross-compile ``core`` and ``alloc``. 53 54If ``rustup`` is being used, run:: 55 56 rustup component add rust-src 57 58The components are installed per toolchain, thus upgrading the Rust compiler 59version later on requires re-adding the component. 60 61Otherwise, if a standalone installer is used, the Rust source tree may be 62downloaded into the toolchain's installation folder:: 63 64 curl -L "https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz" | 65 tar -xzf - -C "$(rustc --print sysroot)/lib" \ 66 "rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/" \ 67 --strip-components=3 68 69In this case, upgrading the Rust compiler version later on requires manually 70updating the source tree (this can be done by removing ``$(rustc --print 71sysroot)/lib/rustlib/src/rust`` then rerunning the above command). 72 73 74libclang 75******** 76 77``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code 78in the kernel, which means LLVM needs to be installed; like when the kernel 79is compiled with ``CC=clang`` or ``LLVM=1``. 80 81Linux distributions are likely to have a suitable one available, so it is 82best to check that first. 83 84There are also some binaries for several systems and architectures uploaded at: 85 86 https://releases.llvm.org/download.html 87 88Otherwise, building LLVM takes quite a while, but it is not a complex process: 89 90 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm 91 92Please see Documentation/kbuild/llvm.rst for more information and further ways 93to fetch pre-built releases and distribution packages. 94 95 96bindgen 97******* 98 99The bindings to the C side of the kernel are generated at build time using 100the ``bindgen`` tool. A particular version is required. 101 102Install it via (note that this will download and build the tool from source):: 103 104 cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli 105 106``bindgen`` needs to find a suitable ``libclang`` in order to work. If it is 107not found (or a different ``libclang`` than the one found should be used), 108the process can be tweaked using the environment variables understood by 109``clang-sys`` (the Rust bindings crate that ``bindgen`` uses to access 110``libclang``): 111 112* ``LLVM_CONFIG_PATH`` can be pointed to an ``llvm-config`` executable. 113 114* Or ``LIBCLANG_PATH`` can be pointed to a ``libclang`` shared library 115 or to the directory containing it. 116 117* Or ``CLANG_PATH`` can be pointed to a ``clang`` executable. 118 119For details, please see ``clang-sys``'s documentation at: 120 121 https://github.com/KyleMayes/clang-sys#environment-variables 122 123 124Requirements: Developing 125------------------------ 126 127This section explains how to fetch the tools needed for developing. That is, 128they are not needed when just building the kernel. 129 130 131rustfmt 132******* 133 134The ``rustfmt`` tool is used to automatically format all the Rust kernel code, 135including the generated C bindings (for details, please see 136coding-guidelines.rst). 137 138If ``rustup`` is being used, its ``default`` profile already installs the tool, 139thus nothing needs to be done. If another profile is being used, the component 140can be installed manually:: 141 142 rustup component add rustfmt 143 144The standalone installers also come with ``rustfmt``. 145 146 147clippy 148****** 149 150``clippy`` is a Rust linter. Running it provides extra warnings for Rust code. 151It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see 152general-information.rst). 153 154If ``rustup`` is being used, its ``default`` profile already installs the tool, 155thus nothing needs to be done. If another profile is being used, the component 156can be installed manually:: 157 158 rustup component add clippy 159 160The standalone installers also come with ``clippy``. 161 162 163cargo 164***** 165 166``cargo`` is the Rust native build system. It is currently required to run 167the tests since it is used to build a custom standard library that contains 168the facilities provided by the custom ``alloc`` in the kernel. The tests can 169be run using the ``rusttest`` Make target. 170 171If ``rustup`` is being used, all the profiles already install the tool, 172thus nothing needs to be done. 173 174The standalone installers also come with ``cargo``. 175 176 177rustdoc 178******* 179 180``rustdoc`` is the documentation tool for Rust. It generates pretty HTML 181documentation for Rust code (for details, please see 182general-information.rst). 183 184``rustdoc`` is also used to test the examples provided in documented Rust code 185(called doctests or documentation tests). The ``rusttest`` Make target uses 186this feature. 187 188If ``rustup`` is being used, all the profiles already install the tool, 189thus nothing needs to be done. 190 191The standalone installers also come with ``rustdoc``. 192 193 194rust-analyzer 195************* 196 197The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can 198be used with many editors to enable syntax highlighting, completion, go to 199definition, and other features. 200 201``rust-analyzer`` needs a configuration file, ``rust-project.json``, which 202can be generated by the ``rust-analyzer`` Make target:: 203 204 make LLVM=1 rust-analyzer 205 206 207Configuration 208------------- 209 210``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup`` 211menu. The option is only shown if a suitable Rust toolchain is found (see 212above), as long as the other requirements are met. In turn, this will make 213visible the rest of options that depend on Rust. 214 215Afterwards, go to:: 216 217 Kernel hacking 218 -> Sample kernel code 219 -> Rust samples 220 221And enable some sample modules either as built-in or as loadable. 222 223 224Building 225-------- 226 227Building a kernel with a complete LLVM toolchain is the best supported setup 228at the moment. That is:: 229 230 make LLVM=1 231 232For architectures that do not support a full LLVM toolchain, use:: 233 234 make CC=clang 235 236Using GCC also works for some configurations, but it is very experimental at 237the moment. 238 239 240Hacking 241------- 242 243To dive deeper, take a look at the source code of the samples 244at ``samples/rust/``, the Rust support code under ``rust/`` and 245the ``Rust hacking`` menu under ``Kernel hacking``. 246 247If GDB/Binutils is used and Rust symbols are not getting demangled, the reason 248is the toolchain does not support Rust's new v0 mangling scheme yet. 249There are a few ways out: 250 251 - Install a newer release (GDB >= 10.2, Binutils >= 2.36). 252 253 - Some versions of GDB (e.g. vanilla GDB 10.1) are able to use 254 the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``). 255