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