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