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