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 Unstable (Sid), outside of the freeze period, provides recent Rust
  43 releases 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
  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 Requirements: Building
  91 ----------------------
  92
  93 This section explains how to fetch the tools needed for building.
  94
  95 To easily check whether the requirements are met, the following target
  96 can be used::
  97
  98         make LLVM=1 rustavailable
  99
 100 This triggers the same logic used by Kconfig to determine whether
 101 ``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not
 102 if that is the case.
 103
 104
 105 rustc
 106 *****
 107
 108 A recent version of the Rust compiler is required.
 109
 110 If ``rustup`` is being used, enter the kernel build directory (or use
 111 ``--path=<build-dir>`` argument to the ``set`` sub-command) and run,
 112 for instance::
 113
 114         rustup override set stable
 115
 116 This will configure your working directory to use the given version of
 117 ``rustc`` without affecting your default toolchain.
 118
 119 Note that the override applies to the current working directory (and its
 120 sub-directories).
 121
 122 If 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
 127 Rust standard library source
 128 ****************************
 129
 130 The Rust standard library source is required because the build system will
 131 cross-compile ``core`` and ``alloc``.
 132
 133 If ``rustup`` is being used, run::
 134
 135         rustup component add rust-src
 136
 137 The components are installed per toolchain, thus upgrading the Rust compiler
 138 version later on requires re-adding the component.
 139
 140 Otherwise, if a standalone installer is used, the Rust source tree may be
 141 downloaded 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
 148 In this case, upgrading the Rust compiler version later on requires manually
 149 updating the source tree (this can be done by removing ``$(rustc --print
 150 sysroot)/lib/rustlib/src/rust`` then rerunning the above command).
 151
 152
 153 libclang
 154 ********
 155
 156 ``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
 157 in the kernel, which means LLVM needs to be installed; like when the kernel
 158 is compiled with ``LLVM=1``.
 159
 160 Linux distributions are likely to have a suitable one available, so it is
 161 best to check that first.
 162
 163 There are also some binaries for several systems and architectures uploaded at:
 164
 165         https://releases.llvm.org/download.html
 166
 167 Otherwise, 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
 171 Please see Documentation/kbuild/llvm.rst for more information and further ways
 172 to fetch pre-built releases and distribution packages.
 173
 174
 175 bindgen
 176 *******
 177
 178 The bindings to the C side of the kernel are generated at build time using
 179 the ``bindgen`` tool.
 180
 181 Install it, for instance, via (note that this will download and build the tool
 182 from source)::
 183
 184         cargo install --locked bindgen-cli
 185
 186 ``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which
 187 may 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
 190 the 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
 192 documentation at:
 193
 194         https://github.com/KyleMayes/clang-sys#linking
 195
 196         https://github.com/KyleMayes/clang-sys#environment-variables
 197
 198
 199 Requirements: Developing
 200 ------------------------
 201
 202 This section explains how to fetch the tools needed for developing. That is,
 203 they are not needed when just building the kernel.
 204
 205
 206 rustfmt
 207 *******
 208
 209 The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
 210 including the generated C bindings (for details, please see
 211 coding-guidelines.rst).
 212
 213 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 214 thus nothing needs to be done. If another profile is being used, the component
 215 can be installed manually::
 216
 217         rustup component add rustfmt
 218
 219 The standalone installers also come with ``rustfmt``.
 220
 221
 222 clippy
 223 ******
 224
 225 ``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
 226 It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
 227 general-information.rst).
 228
 229 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 230 thus nothing needs to be done. If another profile is being used, the component
 231 can be installed manually::
 232
 233         rustup component add clippy
 234
 235 The standalone installers also come with ``clippy``.
 236
 237
 238 rustdoc
 239 *******
 240
 241 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
 242 documentation for Rust code (for details, please see
 243 general-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
 247 this feature.
 248
 249 If ``rustup`` is being used, all the profiles already install the tool,
 250 thus nothing needs to be done.
 251
 252 The standalone installers also come with ``rustdoc``.
 253
 254
 255 rust-analyzer
 256 *************
 257
 258 The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
 259 be used with many editors to enable syntax highlighting, completion, go to
 260 definition, and other features.
 261
 262 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
 263 can be generated by the ``rust-analyzer`` Make target::
 264
 265         make LLVM=1 rust-analyzer
 266
 267
 268 Configuration
 269 -------------
 270
 271 ``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
 272 menu. The option is only shown if a suitable Rust toolchain is found (see
 273 above), as long as the other requirements are met. In turn, this will make
 274 visible the rest of options that depend on Rust.
 275
 276 Afterwards, go to::
 277
 278         Kernel hacking
 279             -> Sample kernel code
 280                 -> Rust samples
 281
 282 And enable some sample modules either as built-in or as loadable.
 283
 284
 285 Building
 286 --------
 287
 288 Building a kernel with a complete LLVM toolchain is the best supported setup
 289 at the moment. That is::
 290
 291         make LLVM=1
 292
 293 Using GCC also works for some configurations, but it is very experimental at
 294 the moment.
 295
 296
 297 Hacking
 298 -------
 299
 300 To dive deeper, take a look at the source code of the samples
 301 at ``samples/rust/``, the Rust support code under ``rust/`` and
 302 the ``Rust hacking`` menu under ``Kernel hacking``.
 303
 304 If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
 305 is the toolchain does not support Rust's new v0 mangling scheme yet.
 306 There 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``).