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 checked out source code directory
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. If you are not using
43 ``rustup``, fetch a standalone installer from:
45 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
48 Rust standard library source
49 ****************************
51 The Rust standard library source is required because the build system will
52 cross-compile ``core`` and ``alloc``.
54 If ``rustup`` is being used, run::
56 rustup component add rust-src
58 The components are installed per toolchain, thus upgrading the Rust compiler
59 version later on requires re-adding the component.
61 Otherwise, if a standalone installer is used, the Rust source tree may be
62 downloaded into the toolchain's installation folder::
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/" \
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).
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``.
81 Linux distributions are likely to have a suitable one available, so it is
82 best to check that first.
84 There are also some binaries for several systems and architectures uploaded at:
86 https://releases.llvm.org/download.html
88 Otherwise, building LLVM takes quite a while, but it is not a complex process:
90 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
92 Please see Documentation/kbuild/llvm.rst for more information and further ways
93 to fetch pre-built releases and distribution packages.
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.
102 Install it via (note that this will download and build the tool from source)::
104 cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli
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
112 * ``LLVM_CONFIG_PATH`` can be pointed to an ``llvm-config`` executable.
114 * Or ``LIBCLANG_PATH`` can be pointed to a ``libclang`` shared library
115 or to the directory containing it.
117 * Or ``CLANG_PATH`` can be pointed to a ``clang`` executable.
119 For details, please see ``clang-sys``'s documentation at:
121 https://github.com/KyleMayes/clang-sys#environment-variables
124 Requirements: Developing
125 ------------------------
127 This section explains how to fetch the tools needed for developing. That is,
128 they are not needed when just building the kernel.
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).
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::
142 rustup component add rustfmt
144 The standalone installers also come with ``rustfmt``.
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).
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::
158 rustup component add clippy
160 The standalone installers also come with ``clippy``.
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.
171 If ``rustup`` is being used, all the profiles already install the tool,
172 thus nothing needs to be done.
174 The standalone installers also come with ``cargo``.
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).
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
188 If ``rustup`` is being used, all the profiles already install the tool,
189 thus nothing needs to be done.
191 The standalone installers also come with ``rustdoc``.
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.
201 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
202 can be generated by the ``rust-analyzer`` Make target::
204 make LLVM=1 rust-analyzer
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.
218 -> Sample kernel code
221 And enable some sample modules either as built-in or as loadable.
227 Building a kernel with a complete LLVM toolchain is the best supported setup
228 at the moment. That is::
232 For architectures that do not support a full LLVM toolchain, use::
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``).