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