Documentation/rust/quick-start.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Quick Start
   4 ===========
   5
   6 This document describes how to get started with kernel development in Rust.
   7
   8 There are a few ways to install a Rust toolchain needed for kernel development.
   9 A simple way is to use the packages from your Linux distribution if they are
  10 suitable -- the first section below explains this approach. An advantage of this
  11 approach is that, typically, the distribution will match the LLVM used by Rust
  12 and Clang.
  13
  14 Another 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
  16 and fast LLVM toolchains from :ref:`Getting LLVM <getting_llvm>` with versions
  17 of 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
  20 Alternatively, the next two "Requirements" sections explain each component and
  21 how to install them through ``rustup``, the standalone installers from Rust
  22 and/or building them.
  23
  24 The rest of the document explains other aspects on how to get started.
  25
  26
  27 Distributions
  28 -------------
  29
  30 Arch Linux
  31 **********
  32
  33 Arch Linux provides recent Rust releases and thus it should generally work out
  34 of the box, e.g.::
  35
  36         pacman -S rust rust-src rust-bindgen
  37
  38
  39 Debian
  40 ******
  41
  42 Debian Testing and Debian Unstable (Sid), outside of the freeze period, provide
  43 recent 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
  48 Fedora Linux
  49 ************
  50
  51 Fedora Linux provides recent Rust releases and thus it should generally work out
  52 of the box, e.g.::
  53
  54         dnf install rust rust-src bindgen-cli rustfmt clippy
  55
  56
  57 Gentoo Linux
  58 ************
  59
  60 Gentoo Linux (and especially the testing branch) provides recent Rust releases
  61 and 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
  68 Nix
  69 ***
  70
  71 Nix (unstable channel) provides recent Rust releases and thus it should
  72 generally 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
  81 openSUSE
  82 ********
  83
  84 openSUSE Slowroll and openSUSE Tumbleweed provide recent Rust releases and thus
  85 they should generally work out of the box, e.g.::
  86
  87         zypper install rust rust1.79-src rust-bindgen clang
  88
  89
  90 Ubuntu
  91 ******
  92
  93 Ubuntu LTS and non-LTS (interim) releases provide recent Rust releases and thus
  94 they 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
 102 In addition, ``bindgen-0.65`` is available in newer releases (24.04 LTS and
 103 24.10), but it may not be available in older ones (20.04 LTS and 22.04 LTS),
 104 thus ``bindgen`` may need to be built manually (please see below).
 105
 106
 107 Requirements: Building
 108 ----------------------
 109
 110 This section explains how to fetch the tools needed for building.
 111
 112 To easily check whether the requirements are met, the following target
 113 can be used::
 114
 115         make LLVM=1 rustavailable
 116
 117 This triggers the same logic used by Kconfig to determine whether
 118 ``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not
 119 if that is the case.
 120
 121
 122 rustc
 123 *****
 124
 125 A recent version of the Rust compiler is required.
 126
 127 If ``rustup`` is being used, enter the kernel build directory (or use
 128 ``--path=<build-dir>`` argument to the ``set`` sub-command) and run,
 129 for instance::
 130
 131         rustup override set stable
 132
 133 This will configure your working directory to use the given version of
 134 ``rustc`` without affecting your default toolchain.
 135
 136 Note that the override applies to the current working directory (and its
 137 sub-directories).
 138
 139 If 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
 144 Rust standard library source
 145 ****************************
 146
 147 The Rust standard library source is required because the build system will
 148 cross-compile ``core`` and ``alloc``.
 149
 150 If ``rustup`` is being used, run::
 151
 152         rustup component add rust-src
 153
 154 The components are installed per toolchain, thus upgrading the Rust compiler
 155 version later on requires re-adding the component.
 156
 157 Otherwise, if a standalone installer is used, the Rust source tree may be
 158 downloaded 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
 165 In this case, upgrading the Rust compiler version later on requires manually
 166 updating the source tree (this can be done by removing ``$(rustc --print
 167 sysroot)/lib/rustlib/src/rust`` then rerunning the above command).
 168
 169
 170 libclang
 171 ********
 172
 173 ``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
 174 in the kernel, which means LLVM needs to be installed; like when the kernel
 175 is compiled with ``LLVM=1``.
 176
 177 Linux distributions are likely to have a suitable one available, so it is
 178 best to check that first.
 179
 180 There are also some binaries for several systems and architectures uploaded at:
 181
 182         https://releases.llvm.org/download.html
 183
 184 Otherwise, 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
 188 Please see Documentation/kbuild/llvm.rst for more information and further ways
 189 to fetch pre-built releases and distribution packages.
 190
 191
 192 bindgen
 193 *******
 194
 195 The bindings to the C side of the kernel are generated at build time using
 196 the ``bindgen`` tool.
 197
 198 Install it, for instance, via (note that this will download and build the tool
 199 from source)::
 200
 201         cargo install --locked bindgen-cli
 202
 203 ``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which
 204 may 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
 207 the 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
 209 documentation at:
 210
 211         https://github.com/KyleMayes/clang-sys#linking
 212
 213         https://github.com/KyleMayes/clang-sys#environment-variables
 214
 215
 216 Requirements: Developing
 217 ------------------------
 218
 219 This section explains how to fetch the tools needed for developing. That is,
 220 they are not needed when just building the kernel.
 221
 222
 223 rustfmt
 224 *******
 225
 226 The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
 227 including the generated C bindings (for details, please see
 228 coding-guidelines.rst).
 229
 230 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 231 thus nothing needs to be done. If another profile is being used, the component
 232 can be installed manually::
 233
 234         rustup component add rustfmt
 235
 236 The standalone installers also come with ``rustfmt``.
 237
 238
 239 clippy
 240 ******
 241
 242 ``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
 243 It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
 244 general-information.rst).
 245
 246 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 247 thus nothing needs to be done. If another profile is being used, the component
 248 can be installed manually::
 249
 250         rustup component add clippy
 251
 252 The standalone installers also come with ``clippy``.
 253
 254
 255 rustdoc
 256 *******
 257
 258 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
 259 documentation for Rust code (for details, please see
 260 general-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
 264 this feature.
 265
 266 If ``rustup`` is being used, all the profiles already install the tool,
 267 thus nothing needs to be done.
 268
 269 The standalone installers also come with ``rustdoc``.
 270
 271
 272 rust-analyzer
 273 *************
 274
 275 The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
 276 be used with many editors to enable syntax highlighting, completion, go to
 277 definition, and other features.
 278
 279 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
 280 can be generated by the ``rust-analyzer`` Make target::
 281
 282         make LLVM=1 rust-analyzer
 283
 284
 285 Configuration
 286 -------------
 287
 288 ``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
 289 menu. The option is only shown if a suitable Rust toolchain is found (see
 290 above), as long as the other requirements are met. In turn, this will make
 291 visible the rest of options that depend on Rust.
 292
 293 Afterwards, go to::
 294
 295         Kernel hacking
 296             -> Sample kernel code
 297                 -> Rust samples
 298
 299 And enable some sample modules either as built-in or as loadable.
 300
 301
 302 Building
 303 --------
 304
 305 Building a kernel with a complete LLVM toolchain is the best supported setup
 306 at the moment. That is::
 307
 308         make LLVM=1
 309
 310 Using GCC also works for some configurations, but it is very experimental at
 311 the moment.
 312
 313
 314 Hacking
 315 -------
 316
 317 To dive deeper, take a look at the source code of the samples
 318 at ``samples/rust/``, the Rust support code under ``rust/`` and
 319 the ``Rust hacking`` menu under ``Kernel hacking``.
 320
 321 If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
 322 is the toolchain does not support Rust's new v0 mangling scheme yet.
 323 There 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``).