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 kernel build directory (or use
  37 ``--path=<build-dir>`` argument to the ``set`` sub-command) and run::
  38
  39         rustup override set $(scripts/min-tool-version.sh rustc)
  40
  41 This will configure your working directory to use the correct version of
  42 ``rustc`` without affecting your default toolchain.
  43
  44 Note that the override applies to the current working directory (and its
  45 sub-directories).
  46
  47 If you are not using ``rustup``, fetch a standalone installer from:
  48
  49         https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
  50
  51
  52 Rust standard library source
  53 ****************************
  54
  55 The Rust standard library source is required because the build system will
  56 cross-compile ``core`` and ``alloc``.
  57
  58 If ``rustup`` is being used, run::
  59
  60         rustup component add rust-src
  61
  62 The components are installed per toolchain, thus upgrading the Rust compiler
  63 version later on requires re-adding the component.
  64
  65 Otherwise, if a standalone installer is used, the Rust source tree may be
  66 downloaded into the toolchain's installation folder::
  67
  68         curl -L "https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz" |
  69                 tar -xzf - -C "$(rustc --print sysroot)/lib" \
  70                 "rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/" \
  71                 --strip-components=3
  72
  73 In this case, upgrading the Rust compiler version later on requires manually
  74 updating the source tree (this can be done by removing ``$(rustc --print
  75 sysroot)/lib/rustlib/src/rust`` then rerunning the above command).
  76
  77
  78 libclang
  79 ********
  80
  81 ``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
  82 in the kernel, which means LLVM needs to be installed; like when the kernel
  83 is compiled with ``LLVM=1``.
  84
  85 Linux distributions are likely to have a suitable one available, so it is
  86 best to check that first.
  87
  88 There are also some binaries for several systems and architectures uploaded at:
  89
  90         https://releases.llvm.org/download.html
  91
  92 Otherwise, building LLVM takes quite a while, but it is not a complex process:
  93
  94         https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
  95
  96 Please see Documentation/kbuild/llvm.rst for more information and further ways
  97 to fetch pre-built releases and distribution packages.
  98
  99
 100 bindgen
 101 *******
 102
 103 The bindings to the C side of the kernel are generated at build time using
 104 the ``bindgen`` tool. A particular version is required.
 105
 106 Install it via (note that this will download and build the tool from source)::
 107
 108         cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli
 109
 110 ``bindgen`` needs to find a suitable ``libclang`` in order to work. If it is
 111 not found (or a different ``libclang`` than the one found should be used),
 112 the process can be tweaked using the environment variables understood by
 113 ``clang-sys`` (the Rust bindings crate that ``bindgen`` uses to access
 114 ``libclang``):
 115
 116 * ``LLVM_CONFIG_PATH`` can be pointed to an ``llvm-config`` executable.
 117
 118 * Or ``LIBCLANG_PATH`` can be pointed to a ``libclang`` shared library
 119   or to the directory containing it.
 120
 121 * Or ``CLANG_PATH`` can be pointed to a ``clang`` executable.
 122
 123 For details, please see ``clang-sys``'s documentation at:
 124
 125         https://github.com/KyleMayes/clang-sys#environment-variables
 126
 127
 128 Requirements: Developing
 129 ------------------------
 130
 131 This section explains how to fetch the tools needed for developing. That is,
 132 they are not needed when just building the kernel.
 133
 134
 135 rustfmt
 136 *******
 137
 138 The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
 139 including the generated C bindings (for details, please see
 140 coding-guidelines.rst).
 141
 142 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 143 thus nothing needs to be done. If another profile is being used, the component
 144 can be installed manually::
 145
 146         rustup component add rustfmt
 147
 148 The standalone installers also come with ``rustfmt``.
 149
 150
 151 clippy
 152 ******
 153
 154 ``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
 155 It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
 156 general-information.rst).
 157
 158 If ``rustup`` is being used, its ``default`` profile already installs the tool,
 159 thus nothing needs to be done. If another profile is being used, the component
 160 can be installed manually::
 161
 162         rustup component add clippy
 163
 164 The standalone installers also come with ``clippy``.
 165
 166
 167 cargo
 168 *****
 169
 170 ``cargo`` is the Rust native build system. It is currently required to run
 171 the tests since it is used to build a custom standard library that contains
 172 the facilities provided by the custom ``alloc`` in the kernel. The tests can
 173 be run using the ``rusttest`` Make target.
 174
 175 If ``rustup`` is being used, all the profiles already install the tool,
 176 thus nothing needs to be done.
 177
 178 The standalone installers also come with ``cargo``.
 179
 180
 181 rustdoc
 182 *******
 183
 184 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
 185 documentation for Rust code (for details, please see
 186 general-information.rst).
 187
 188 ``rustdoc`` is also used to test the examples provided in documented Rust code
 189 (called doctests or documentation tests). The ``rusttest`` Make target uses
 190 this feature.
 191
 192 If ``rustup`` is being used, all the profiles already install the tool,
 193 thus nothing needs to be done.
 194
 195 The standalone installers also come with ``rustdoc``.
 196
 197
 198 rust-analyzer
 199 *************
 200
 201 The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
 202 be used with many editors to enable syntax highlighting, completion, go to
 203 definition, and other features.
 204
 205 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
 206 can be generated by the ``rust-analyzer`` Make target::
 207
 208         make LLVM=1 rust-analyzer
 209
 210
 211 Configuration
 212 -------------
 213
 214 ``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
 215 menu. The option is only shown if a suitable Rust toolchain is found (see
 216 above), as long as the other requirements are met. In turn, this will make
 217 visible the rest of options that depend on Rust.
 218
 219 Afterwards, go to::
 220
 221         Kernel hacking
 222             -> Sample kernel code
 223                 -> Rust samples
 224
 225 And enable some sample modules either as built-in or as loadable.
 226
 227
 228 Building
 229 --------
 230
 231 Building a kernel with a complete LLVM toolchain is the best supported setup
 232 at the moment. That is::
 233
 234         make LLVM=1
 235
 236 Using GCC also works for some configurations, but it is very experimental at
 237 the moment.
 238
 239
 240 Hacking
 241 -------
 242
 243 To dive deeper, take a look at the source code of the samples
 244 at ``samples/rust/``, the Rust support code under ``rust/`` and
 245 the ``Rust hacking`` menu under ``Kernel hacking``.
 246
 247 If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
 248 is the toolchain does not support Rust's new v0 mangling scheme yet.
 249 There are a few ways out:
 250
 251   - Install a newer release (GDB >= 10.2, Binutils >= 2.36).
 252
 253   - Some versions of GDB (e.g. vanilla GDB 10.1) are able to use
 254     the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``).