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 Testing and Debian Unstable (Sid), outside of the freeze period, provide 43recent Rust releases and thus they 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 90Ubuntu 91****** 92 9325.04 94~~~~~ 95 96The latest Ubuntu releases provide recent Rust releases and thus they should 97generally work out of the box, e.g.:: 98 99 apt install rustc rust-src bindgen rustfmt rust-clippy 100 101In addition, ``RUST_LIB_SRC`` needs to be set, e.g.:: 102 103 RUST_LIB_SRC=/usr/src/rustc-$(rustc --version | cut -d' ' -f2)/library 104 105For convenience, ``RUST_LIB_SRC`` can be exported to the global environment. 106 107 10824.04 LTS and older 109~~~~~~~~~~~~~~~~~~~ 110 111Though Ubuntu 24.04 LTS and older versions still provide recent Rust 112releases, they require some additional configuration to be set, using 113the versioned packages, e.g.:: 114 115 apt install rustc-1.80 rust-1.80-src bindgen-0.65 rustfmt-1.80 \ 116 rust-1.80-clippy 117 ln -s /usr/lib/rust-1.80/bin/rustfmt /usr/bin/rustfmt-1.80 118 ln -s /usr/lib/rust-1.80/bin/clippy-driver /usr/bin/clippy-driver-1.80 119 120None of these packages set their tools as defaults; therefore they should be 121specified explicitly, e.g.:: 122 123 make LLVM=1 RUSTC=rustc-1.80 RUSTDOC=rustdoc-1.80 RUSTFMT=rustfmt-1.80 \ 124 CLIPPY_DRIVER=clippy-driver-1.80 BINDGEN=bindgen-0.65 125 126Alternatively, modify the ``PATH`` variable to place the Rust 1.80 binaries 127first and set ``bindgen`` as the default, e.g.:: 128 129 PATH=/usr/lib/rust-1.80/bin:$PATH 130 update-alternatives --install /usr/bin/bindgen bindgen \ 131 /usr/bin/bindgen-0.65 100 132 update-alternatives --set bindgen /usr/bin/bindgen-0.65 133 134``RUST_LIB_SRC`` needs to be set when using the versioned packages, e.g.:: 135 136 RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.80 --version | cut -d' ' -f2)/library 137 138For convenience, ``RUST_LIB_SRC`` can be exported to the global environment. 139 140In addition, ``bindgen-0.65`` is available in newer releases (24.04 LTS and 14124.10), but it may not be available in older ones (20.04 LTS and 22.04 LTS), 142thus ``bindgen`` may need to be built manually (please see below). 143 144 145Requirements: Building 146---------------------- 147 148This section explains how to fetch the tools needed for building. 149 150To easily check whether the requirements are met, the following target 151can be used:: 152 153 make LLVM=1 rustavailable 154 155This triggers the same logic used by Kconfig to determine whether 156``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not 157if that is the case. 158 159 160rustc 161***** 162 163A recent version of the Rust compiler is required. 164 165If ``rustup`` is being used, enter the kernel build directory (or use 166``--path=<build-dir>`` argument to the ``set`` sub-command) and run, 167for instance:: 168 169 rustup override set stable 170 171This will configure your working directory to use the given version of 172``rustc`` without affecting your default toolchain. 173 174Note that the override applies to the current working directory (and its 175sub-directories). 176 177If you are not using ``rustup``, fetch a standalone installer from: 178 179 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone 180 181 182Rust standard library source 183**************************** 184 185The Rust standard library source is required because the build system will 186cross-compile ``core``. 187 188If ``rustup`` is being used, run:: 189 190 rustup component add rust-src 191 192The components are installed per toolchain, thus upgrading the Rust compiler 193version later on requires re-adding the component. 194 195Otherwise, if a standalone installer is used, the Rust source tree may be 196downloaded into the toolchain's installation folder:: 197 198 curl -L "https://static.rust-lang.org/dist/rust-src-$(rustc --version | cut -d' ' -f2).tar.gz" | 199 tar -xzf - -C "$(rustc --print sysroot)/lib" \ 200 "rust-src-$(rustc --version | cut -d' ' -f2)/rust-src/lib/" \ 201 --strip-components=3 202 203In this case, upgrading the Rust compiler version later on requires manually 204updating the source tree (this can be done by removing ``$(rustc --print 205sysroot)/lib/rustlib/src/rust`` then rerunning the above command). 206 207 208libclang 209******** 210 211``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code 212in the kernel, which means LLVM needs to be installed; like when the kernel 213is compiled with ``LLVM=1``. 214 215Linux distributions are likely to have a suitable one available, so it is 216best to check that first. 217 218There are also some binaries for several systems and architectures uploaded at: 219 220 https://releases.llvm.org/download.html 221 222Otherwise, building LLVM takes quite a while, but it is not a complex process: 223 224 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm 225 226Please see Documentation/kbuild/llvm.rst for more information and further ways 227to fetch pre-built releases and distribution packages. 228 229 230bindgen 231******* 232 233The bindings to the C side of the kernel are generated at build time using 234the ``bindgen`` tool. 235 236Install it, for instance, via (note that this will download and build the tool 237from source):: 238 239 cargo install --locked bindgen-cli 240 241``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which 242may be linked statically, dynamically or loaded at runtime). By default, the 243``cargo`` command above will produce a ``bindgen`` binary that will load 244``libclang`` at runtime. If it is not found (or a different ``libclang`` than 245the one found should be used), the process can be tweaked, e.g. by using the 246``LIBCLANG_PATH`` environment variable. For details, please see ``clang-sys``'s 247documentation at: 248 249 https://github.com/KyleMayes/clang-sys#linking 250 251 https://github.com/KyleMayes/clang-sys#environment-variables 252 253 254Requirements: Developing 255------------------------ 256 257This section explains how to fetch the tools needed for developing. That is, 258they are not needed when just building the kernel. 259 260 261rustfmt 262******* 263 264The ``rustfmt`` tool is used to automatically format all the Rust kernel code, 265including the generated C bindings (for details, please see 266coding-guidelines.rst). 267 268If ``rustup`` is being used, its ``default`` profile already installs the tool, 269thus nothing needs to be done. If another profile is being used, the component 270can be installed manually:: 271 272 rustup component add rustfmt 273 274The standalone installers also come with ``rustfmt``. 275 276 277clippy 278****** 279 280``clippy`` is a Rust linter. Running it provides extra warnings for Rust code. 281It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see 282general-information.rst). 283 284If ``rustup`` is being used, its ``default`` profile already installs the tool, 285thus nothing needs to be done. If another profile is being used, the component 286can be installed manually:: 287 288 rustup component add clippy 289 290The standalone installers also come with ``clippy``. 291 292 293rustdoc 294******* 295 296``rustdoc`` is the documentation tool for Rust. It generates pretty HTML 297documentation for Rust code (for details, please see 298general-information.rst). 299 300``rustdoc`` is also used to test the examples provided in documented Rust code 301(called doctests or documentation tests). The ``rusttest`` Make target uses 302this feature. 303 304If ``rustup`` is being used, all the profiles already install the tool, 305thus nothing needs to be done. 306 307The standalone installers also come with ``rustdoc``. 308 309 310rust-analyzer 311************* 312 313The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can 314be used with many editors to enable syntax highlighting, completion, go to 315definition, and other features. 316 317``rust-analyzer`` needs a configuration file, ``rust-project.json``, which 318can be generated by the ``rust-analyzer`` Make target:: 319 320 make LLVM=1 rust-analyzer 321 322 323Configuration 324------------- 325 326``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup`` 327menu. The option is only shown if a suitable Rust toolchain is found (see 328above), as long as the other requirements are met. In turn, this will make 329visible the rest of options that depend on Rust. 330 331Afterwards, go to:: 332 333 Kernel hacking 334 -> Sample kernel code 335 -> Rust samples 336 337And enable some sample modules either as built-in or as loadable. 338 339 340Building 341-------- 342 343Building a kernel with a complete LLVM toolchain is the best supported setup 344at the moment. That is:: 345 346 make LLVM=1 347 348Using GCC also works for some configurations, but it is very experimental at 349the moment. 350 351 352Hacking 353------- 354 355To dive deeper, take a look at the source code of the samples 356at ``samples/rust/``, the Rust support code under ``rust/`` and 357the ``Rust hacking`` menu under ``Kernel hacking``. 358 359If GDB/Binutils is used and Rust symbols are not getting demangled, the reason 360is the toolchain does not support Rust's new v0 mangling scheme yet. 361There are a few ways out: 362 363- Install a newer release (GDB >= 10.2, Binutils >= 2.36). 364 365- Some versions of GDB (e.g. vanilla GDB 10.1) are able to use 366 the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``). 367