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
   9 Requirements: Building
  10 ----------------------
  11
  12 This section explains how to fetch the tools needed for building.
  13
  14 Some of these requirements might be available from Linux distributions
  15 under names like ``rustc``, ``rust-src``, ``rust-bindgen``, etc. However,
  16 at the time of writing, they are likely not to be recent enough unless
  17 the distribution tracks the latest releases.
  18
  19 To easily check whether the requirements are met, the following target
  20 can be used::
  21
  22         make LLVM=1 rustavailable
  23
  24 This triggers the same logic used by Kconfig to determine whether
  25 ``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not
  26 if that is the case.
  27
  28
  29 rustc
  30 *****
  31
  32 A particular version of the Rust compiler is required. Newer versions may or
  33 may not work because, for the moment, the kernel depends on some unstable
  34 Rust features.
  35
  36 If ``rustup`` is being used, enter the checked out source code directory
  37 and run::
  38
  39         rustup override set $(scripts/min-tool-version.sh rustc)
  40
  41 Otherwise, fetch a standalone installer or install ``rustup`` from:
  42
  43         https://www.rust-lang.org
  44
  45
  46 Rust standard library source
  47 ****************************
  48
  49 The Rust standard library source is required because the build system will
  50 cross-compile ``core`` and ``alloc``.
  51
  52 If ``rustup`` is being used, run::
  53
  54         rustup component add rust-src
  55
  56 The components are installed per toolchain, thus upgrading the Rust compiler
  57 version later on requires re-adding the component.
  58
  59 Otherwise, if a standalone installer is used, the Rust repository may be cloned
  60 into the installation folder of the toolchain::
  61
  62         git clone --recurse-submodules \
  63                 --branch $(scripts/min-tool-version.sh rustc) \
  64                 https://github.com/rust-lang/rust \
  65                 $(rustc --print sysroot)/lib/rustlib/src/rust
  66
  67 In this case, upgrading the Rust compiler version later on requires manually
  68 updating this clone.
  69
  70
  71 libclang
  72 ********
  73
  74 ``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
  75 in the kernel, which means LLVM needs to be installed; like when the kernel
  76 is compiled with ``CC=clang`` or ``LLVM=1``.
  77
  78 Linux distributions are likely to have a suitable one available, so it is
  79 best to check that first.
  80
  81 There are also some binaries for several systems and architectures uploaded at:
  82
  83         https://releases.llvm.org/download.html
  84
  85 Otherwise, building LLVM takes quite a while, but it is not a complex process:
  86
  87         https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
  88
  89 Please see Documentation/kbuild/llvm.rst for more information and further ways
  90 to fetch pre-built releases and distribution packages.
  91
  92
  93 bindgen
  94 *******
  95
  96 The bindings to the C side of the kernel are generated at build time using
  97 the ``bindgen`` tool. A particular version is required.
  98
  99 Install it via (note that this will download and build the tool from source)::
 100
 101         cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen
 102
 103
 104 Requirements: Developing
 105 ------------------------
 106
 107 This section explains how to fetch the tools needed for developing. That is,
 108 they are not needed when just building the kernel.
 109
 110
 111 rustfmt
 112 *******
 113
 114 The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
 115 including the generated C bindings (for details, please see
 116 coding-guidelines.rst).
 117
 118 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 119 thus nothing needs to be done. If another profile is being used, the component
 120 can be installed manually::
 121
 122         rustup component add rustfmt
 123
 124 The standalone installers also come with ``rustfmt``.
 125
 126
 127 clippy
 128 ******
 129
 130 ``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
 131 It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
 132 general-information.rst).
 133
 134 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 135 thus nothing needs to be done. If another profile is being used, the component
 136 can be installed manually::
 137
 138         rustup component add clippy
 139
 140 The standalone installers also come with ``clippy``.
 141
 142
 143 cargo
 144 *****
 145
 146 ``cargo`` is the Rust native build system. It is currently required to run
 147 the tests since it is used to build a custom standard library that contains
 148 the facilities provided by the custom ``alloc`` in the kernel. The tests can
 149 be run using the ``rusttest`` Make target.
 150
 151 If ``rustup`` is being used, all the profiles already install the tool,
 152 thus nothing needs to be done.
 153
 154 The standalone installers also come with ``cargo``.
 155
 156
 157 rustdoc
 158 *******
 159
 160 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
 161 documentation for Rust code (for details, please see
 162 general-information.rst).
 163
 164 ``rustdoc`` is also used to test the examples provided in documented Rust code
 165 (called doctests or documentation tests). The ``rusttest`` Make target uses
 166 this feature.
 167
 168 If ``rustup`` is being used, all the profiles already install the tool,
 169 thus nothing needs to be done.
 170
 171 The standalone installers also come with ``rustdoc``.
 172
 173
 174 rust-analyzer
 175 *************
 176
 177 The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
 178 be used with many editors to enable syntax highlighting, completion, go to
 179 definition, and other features.
 180
 181 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
 182 can be generated by the ``rust-analyzer`` Make target.
 183
 184
 185 Configuration
 186 -------------
 187
 188 ``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
 189 menu. The option is only shown if a suitable Rust toolchain is found (see
 190 above), as long as the other requirements are met. In turn, this will make
 191 visible the rest of options that depend on Rust.
 192
 193 Afterwards, go to::
 194
 195         Kernel hacking
 196             -> Sample kernel code
 197                 -> Rust samples
 198
 199 And enable some sample modules either as built-in or as loadable.
 200
 201
 202 Building
 203 --------
 204
 205 Building a kernel with a complete LLVM toolchain is the best supported setup
 206 at the moment. That is::
 207
 208         make LLVM=1
 209
 210 For architectures that do not support a full LLVM toolchain, use::
 211
 212         make CC=clang
 213
 214 Using GCC also works for some configurations, but it is very experimental at
 215 the moment.
 216
 217
 218 Hacking
 219 -------
 220
 221 To dive deeper, take a look at the source code of the samples
 222 at ``samples/rust/``, the Rust support code under ``rust/`` and
 223 the ``Rust hacking`` menu under ``Kernel hacking``.
 224
 225 If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
 226 is the toolchain does not support Rust's new v0 mangling scheme yet.
 227 There are a few ways out:
 228
 229   - Install a newer release (GDB >= 10.2, Binutils >= 2.36).
 230
 231   - Some versions of GDB (e.g. vanilla GDB 10.1) are able to use
 232     the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``).