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 8There are a few ways to install a Rust toolchain needed for kernel development. 9A simple way is to use the packages from your Linux distribution if they are 10suitable -- the first section below explains this approach. An advantage of this 11approach is that, typically, the distribution will match the LLVM used by Rust 12and Clang. 13 14Another way is using the prebuilt stable versions of LLVM+Rust provided on 15`kernel.org <https://kernel.org/pub/tools/llvm/rust/>`_. These are the same slim 16and fast LLVM toolchains from :ref:`Getting LLVM <getting_llvm>` with versions 17of Rust added to them that Rust for Linux supports. Two sets are provided: the 18"latest LLVM" and "matching LLVM" (please see the link for more information). 19 20Alternatively, the next two "Requirements" sections explain each component and 21how to install them through ``rustup``, the standalone installers from Rust 22and/or building them. 23 24The rest of the document explains other aspects on how to get started. 25 26 27Distributions 28------------- 29 30Arch Linux 31********** 32 33Arch Linux provides recent Rust releases and thus it should generally work out 34of the box, e.g.:: 35 36 pacman -S rust rust-src rust-bindgen 37 38 39Debian 40****** 41 42Debian Unstable (Sid), outside of the freeze period, provides recent Rust 43releases and thus it should generally work out of the box, e.g.:: 44 45 apt install rustc rust-src bindgen rustfmt rust-clippy 46 47 48Fedora Linux 49************ 50 51Fedora Linux provides recent Rust releases and thus it should generally work out 52of the box, e.g.:: 53 54 dnf install rust rust-src bindgen-cli rustfmt clippy 55 56 57Gentoo Linux 58************ 59 60Gentoo Linux (and especially the testing branch) provides recent Rust releases 61and thus it should generally work out of the box, e.g.:: 62 63 USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen 64 65``LIBCLANG_PATH`` may need to be set. 66 67 68Nix 69*** 70 71Nix (unstable channel) provides recent Rust releases and thus it should 72generally work out of the box, e.g.:: 73 74 { pkgs ? import <nixpkgs> {} }: 75 pkgs.mkShell { 76 nativeBuildInputs = with pkgs; [ rustc rust-bindgen rustfmt clippy ]; 77 RUST_LIB_SRC = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; 78 } 79 80 81openSUSE 82******** 83 84openSUSE Slowroll and openSUSE Tumbleweed provide recent Rust releases and thus 85they should generally work out of the box, e.g.:: 86 87 zypper install rust rust1.79-src rust-bindgen clang 88 89 90Requirements: Building 91---------------------- 92 93This section explains how to fetch the tools needed for building. 94 95To easily check whether the requirements are met, the following target 96can be used:: 97 98 make LLVM=1 rustavailable 99 100This triggers the same logic used by Kconfig to determine whether 101``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not 102if that is the case. 103 104 105rustc 106***** 107 108A recent version of the Rust compiler is required. 109 110If ``rustup`` is being used, enter the kernel build directory (or use 111``--path=<build-dir>`` argument to the ``set`` sub-command) and run, 112for instance:: 113 114 rustup override set stable 115 116This will configure your working directory to use the given version of 117``rustc`` without affecting your default toolchain. 118 119Note that the override applies to the current working directory (and its 120sub-directories). 121 122If you are not using ``rustup``, fetch a standalone installer from: 123 124 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone 125 126 127Rust standard library source 128**************************** 129 130The Rust standard library source is required because the build system will 131cross-compile ``core`` and ``alloc``. 132 133If ``rustup`` is being used, run:: 134 135 rustup component add rust-src 136 137The components are installed per toolchain, thus upgrading the Rust compiler 138version later on requires re-adding the component. 139 140Otherwise, if a standalone installer is used, the Rust source tree may be 141downloaded into the toolchain's installation folder:: 142 143 curl -L "https://static.rust-lang.org/dist/rust-src-$(rustc --version | cut -d' ' -f2).tar.gz" | 144 tar -xzf - -C "$(rustc --print sysroot)/lib" \ 145 "rust-src-$(rustc --version | cut -d' ' -f2)/rust-src/lib/" \ 146 --strip-components=3 147 148In this case, upgrading the Rust compiler version later on requires manually 149updating the source tree (this can be done by removing ``$(rustc --print 150sysroot)/lib/rustlib/src/rust`` then rerunning the above command). 151 152 153libclang 154******** 155 156``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code 157in the kernel, which means LLVM needs to be installed; like when the kernel 158is compiled with ``LLVM=1``. 159 160Linux distributions are likely to have a suitable one available, so it is 161best to check that first. 162 163There are also some binaries for several systems and architectures uploaded at: 164 165 https://releases.llvm.org/download.html 166 167Otherwise, building LLVM takes quite a while, but it is not a complex process: 168 169 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm 170 171Please see Documentation/kbuild/llvm.rst for more information and further ways 172to fetch pre-built releases and distribution packages. 173 174 175bindgen 176******* 177 178The bindings to the C side of the kernel are generated at build time using 179the ``bindgen`` tool. 180 181Install it, for instance, via (note that this will download and build the tool 182from source):: 183 184 cargo install --locked bindgen-cli 185 186``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which 187may be linked statically, dynamically or loaded at runtime). By default, the 188``cargo`` command above will produce a ``bindgen`` binary that will load 189``libclang`` at runtime. If it is not found (or a different ``libclang`` than 190the one found should be used), the process can be tweaked, e.g. by using the 191``LIBCLANG_PATH`` environment variable. For details, please see ``clang-sys``'s 192documentation at: 193 194 https://github.com/KyleMayes/clang-sys#linking 195 196 https://github.com/KyleMayes/clang-sys#environment-variables 197 198 199Requirements: Developing 200------------------------ 201 202This section explains how to fetch the tools needed for developing. That is, 203they are not needed when just building the kernel. 204 205 206rustfmt 207******* 208 209The ``rustfmt`` tool is used to automatically format all the Rust kernel code, 210including the generated C bindings (for details, please see 211coding-guidelines.rst). 212 213If ``rustup`` is being used, its ``default`` profile already installs the tool, 214thus nothing needs to be done. If another profile is being used, the component 215can be installed manually:: 216 217 rustup component add rustfmt 218 219The standalone installers also come with ``rustfmt``. 220 221 222clippy 223****** 224 225``clippy`` is a Rust linter. Running it provides extra warnings for Rust code. 226It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see 227general-information.rst). 228 229If ``rustup`` is being used, its ``default`` profile already installs the tool, 230thus nothing needs to be done. If another profile is being used, the component 231can be installed manually:: 232 233 rustup component add clippy 234 235The standalone installers also come with ``clippy``. 236 237 238rustdoc 239******* 240 241``rustdoc`` is the documentation tool for Rust. It generates pretty HTML 242documentation for Rust code (for details, please see 243general-information.rst). 244 245``rustdoc`` is also used to test the examples provided in documented Rust code 246(called doctests or documentation tests). The ``rusttest`` Make target uses 247this feature. 248 249If ``rustup`` is being used, all the profiles already install the tool, 250thus nothing needs to be done. 251 252The standalone installers also come with ``rustdoc``. 253 254 255rust-analyzer 256************* 257 258The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can 259be used with many editors to enable syntax highlighting, completion, go to 260definition, and other features. 261 262``rust-analyzer`` needs a configuration file, ``rust-project.json``, which 263can be generated by the ``rust-analyzer`` Make target:: 264 265 make LLVM=1 rust-analyzer 266 267 268Configuration 269------------- 270 271``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup`` 272menu. The option is only shown if a suitable Rust toolchain is found (see 273above), as long as the other requirements are met. In turn, this will make 274visible the rest of options that depend on Rust. 275 276Afterwards, go to:: 277 278 Kernel hacking 279 -> Sample kernel code 280 -> Rust samples 281 282And enable some sample modules either as built-in or as loadable. 283 284 285Building 286-------- 287 288Building a kernel with a complete LLVM toolchain is the best supported setup 289at the moment. That is:: 290 291 make LLVM=1 292 293Using GCC also works for some configurations, but it is very experimental at 294the moment. 295 296 297Hacking 298------- 299 300To dive deeper, take a look at the source code of the samples 301at ``samples/rust/``, the Rust support code under ``rust/`` and 302the ``Rust hacking`` menu under ``Kernel hacking``. 303 304If GDB/Binutils is used and Rust symbols are not getting demangled, the reason 305is the toolchain does not support Rust's new v0 mangling scheme yet. 306There are a few ways out: 307 308 - Install a newer release (GDB >= 10.2, Binutils >= 2.36). 309 310 - Some versions of GDB (e.g. vanilla GDB 10.1) are able to use 311 the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``). 312