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