1 .. SPDX-License-Identifier: GPL-2.0
6 This document describes how to get started with kernel development in Rust.
10 ----------------------
12 This section explains how to fetch the tools needed for building.
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.
19 To easily check whether the requirements are met, the following target
22 make LLVM=1 rustavailable
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
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
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::
39 rustup override set $(scripts/min-tool-version.sh rustc)
41 This will configure your working directory to use the correct version of
42 ``rustc`` without affecting your default toolchain.
44 Note that the override applies to the current working directory (and its
47 If you are not using ``rustup``, fetch a standalone installer from:
49 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
52 Rust standard library source
53 ****************************
55 The Rust standard library source is required because the build system will
56 cross-compile ``core`` and ``alloc``.
58 If ``rustup`` is being used, run::
60 rustup component add rust-src
62 The components are installed per toolchain, thus upgrading the Rust compiler
63 version later on requires re-adding the component.
65 Otherwise, if a standalone installer is used, the Rust source tree may be
66 downloaded into the toolchain's installation folder::
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/" \
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).
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``.
85 Linux distributions are likely to have a suitable one available, so it is
86 best to check that first.
88 There are also some binaries for several systems and architectures uploaded at:
90 https://releases.llvm.org/download.html
92 Otherwise, building LLVM takes quite a while, but it is not a complex process:
94 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
96 Please see Documentation/kbuild/llvm.rst for more information and further ways
97 to fetch pre-built releases and distribution packages.
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.
106 Install it via (note that this will download and build the tool from source)::
108 cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli
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
116 * ``LLVM_CONFIG_PATH`` can be pointed to an ``llvm-config`` executable.
118 * Or ``LIBCLANG_PATH`` can be pointed to a ``libclang`` shared library
119 or to the directory containing it.
121 * Or ``CLANG_PATH`` can be pointed to a ``clang`` executable.
123 For details, please see ``clang-sys``'s documentation at:
125 https://github.com/KyleMayes/clang-sys#environment-variables
128 Requirements: Developing
129 ------------------------
131 This section explains how to fetch the tools needed for developing. That is,
132 they are not needed when just building the kernel.
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).
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::
146 rustup component add rustfmt
148 The standalone installers also come with ``rustfmt``.
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).
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::
162 rustup component add clippy
164 The standalone installers also come with ``clippy``.
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.
175 If ``rustup`` is being used, all the profiles already install the tool,
176 thus nothing needs to be done.
178 The standalone installers also come with ``cargo``.
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).
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
192 If ``rustup`` is being used, all the profiles already install the tool,
193 thus nothing needs to be done.
195 The standalone installers also come with ``rustdoc``.
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.
205 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
206 can be generated by the ``rust-analyzer`` Make target::
208 make LLVM=1 rust-analyzer
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.
222 -> Sample kernel code
225 And enable some sample modules either as built-in or as loadable.
231 Building a kernel with a complete LLVM toolchain is the best supported setup
232 at the moment. That is::
236 Using GCC also works for some configurations, but it is very experimental at
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``.
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:
251 - Install a newer release (GDB >= 10.2, Binutils >= 2.36).
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``).