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