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