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 There are a few ways to install a Rust toolchain needed for kernel development.
9 A simple way is to use the packages from your Linux distribution if they are
10 suitable -- the first section below explains this approach. An advantage of this
11 approach is that, typically, the distribution will match the LLVM used by Rust
12 and Clang.
13
14 Another way is using the prebuilt stable versions of LLVM+Rust provided on
15 `kernel.org <https://kernel.org/pub/tools/llvm/rust/>`_. These are the same slim
16 and fast LLVM toolchains from :ref:`Getting LLVM <getting_llvm>` with versions
17 of Rust added to them that Rust for Linux supports. Two sets are provided: the
18 "latest LLVM" and "matching LLVM" (please see the link for more information).
19
20 Alternatively, the next two "Requirements" sections explain each component and
21 how to install them through ``rustup``, the standalone installers from Rust
22 and/or building them.
23
24 The rest of the document explains other aspects on how to get started.
25
26
27 Distributions
28 -------------
29
30 Arch Linux
31 **********
32
33 Arch Linux provides recent Rust releases and thus it should generally work out
34 of the box, e.g.::
35
36 pacman -S rust rust-src rust-bindgen
37
38
39 Debian
40 ******
41
42 Debian Unstable (Sid), outside of the freeze period, provides recent Rust
43 releases and thus it should generally work out of the box, e.g.::
44
45 apt install rustc rust-src bindgen rustfmt rust-clippy
46
47
48 Fedora Linux
49 ************
50
51 Fedora Linux provides recent Rust releases and thus it should generally work out
52 of the box, e.g.::
53
54 dnf install rust rust-src bindgen-cli rustfmt clippy
55
56
57 Gentoo Linux
58 ************
59
60 Gentoo Linux (and especially the testing branch) provides recent Rust releases
61 and thus it should generally work out of the box, e.g.::
62
63 USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen
64
65 ``LIBCLANG_PATH`` may need to be set.
66
67
68 Nix
69 ***
70
71 Nix (unstable channel) provides recent Rust releases and thus it should
72 generally work out of the box, e.g.::
73
74 { pkgs ? import <nixpkgs> {} }:
75 pkgs.mkShell {
76 nativeBuildInputs = with pkgs; [ rustc rust-bindgen rustfmt clippy ];
77 RUST_LIB_SRC = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}";
78 }
79
80
81 openSUSE
82 ********
83
84 openSUSE Slowroll and openSUSE Tumbleweed provide recent Rust releases and thus
85 they should generally work out of the box, e.g.::
86
87 zypper install rust rust1.79-src rust-bindgen clang
88
89
90 Requirements: Building
91 ----------------------
92
93 This section explains how to fetch the tools needed for building.
94
95 To easily check whether the requirements are met, the following target
96 can be used::
97
98 make LLVM=1 rustavailable
99
100 This triggers the same logic used by Kconfig to determine whether
101 ``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not
102 if that is the case.
103
104
105 rustc
106 *****
107
108 A recent version of the Rust compiler is required.
109
110 If ``rustup`` is being used, enter the kernel build directory (or use
111 ``--path=<build-dir>`` argument to the ``set`` sub-command) and run,
112 for instance::
113
114 rustup override set stable
115
116 This will configure your working directory to use the given version of
117 ``rustc`` without affecting your default toolchain.
118
119 Note that the override applies to the current working directory (and its
120 sub-directories).
121
122 If you are not using ``rustup``, fetch a standalone installer from:
123
124 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
125
126
127 Rust standard library source
128 ****************************
129
130 The Rust standard library source is required because the build system will
131 cross-compile ``core`` and ``alloc``.
132
133 If ``rustup`` is being used, run::
134
135 rustup component add rust-src
136
137 The components are installed per toolchain, thus upgrading the Rust compiler
138 version later on requires re-adding the component.
139
140 Otherwise, if a standalone installer is used, the Rust source tree may be
141 downloaded into the toolchain's installation folder::
142
143 curl -L "https://static.rust-lang.org/dist/rust-src-$(rustc --version | cut -d' ' -f2).tar.gz" |
144 tar -xzf - -C "$(rustc --print sysroot)/lib" \
145 "rust-src-$(rustc --version | cut -d' ' -f2)/rust-src/lib/" \
146 --strip-components=3
147
148 In this case, upgrading the Rust compiler version later on requires manually
149 updating the source tree (this can be done by removing ``$(rustc --print
150 sysroot)/lib/rustlib/src/rust`` then rerunning the above command).
151
152
153 libclang
154 ********
155
156 ``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
157 in the kernel, which means LLVM needs to be installed; like when the kernel
158 is compiled with ``LLVM=1``.
159
160 Linux distributions are likely to have a suitable one available, so it is
161 best to check that first.
162
163 There are also some binaries for several systems and architectures uploaded at:
164
165 https://releases.llvm.org/download.html
166
167 Otherwise, building LLVM takes quite a while, but it is not a complex process:
168
169 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
170
171 Please see Documentation/kbuild/llvm.rst for more information and further ways
172 to fetch pre-built releases and distribution packages.
173
174
175 bindgen
176 *******
177
178 The bindings to the C side of the kernel are generated at build time using
179 the ``bindgen`` tool.
180
181 Install it, for instance, via (note that this will download and build the tool
182 from source)::
183
184 cargo install --locked bindgen-cli
185
186 ``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which
187 may be linked statically, dynamically or loaded at runtime). By default, the
188 ``cargo`` command above will produce a ``bindgen`` binary that will load
189 ``libclang`` at runtime. If it is not found (or a different ``libclang`` than
190 the one found should be used), the process can be tweaked, e.g. by using the
191 ``LIBCLANG_PATH`` environment variable. For details, please see ``clang-sys``'s
192 documentation at:
193
194 https://github.com/KyleMayes/clang-sys#linking
195
196 https://github.com/KyleMayes/clang-sys#environment-variables
197
198
199 Requirements: Developing
200 ------------------------
201
202 This section explains how to fetch the tools needed for developing. That is,
203 they are not needed when just building the kernel.
204
205
206 rustfmt
207 *******
208
209 The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
210 including the generated C bindings (for details, please see
211 coding-guidelines.rst).
212
213 If ``rustup`` is being used, its ``default`` profile already installs the tool,
214 thus nothing needs to be done. If another profile is being used, the component
215 can be installed manually::
216
217 rustup component add rustfmt
218
219 The standalone installers also come with ``rustfmt``.
220
221
222 clippy
223 ******
224
225 ``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
226 It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
227 general-information.rst).
228
229 If ``rustup`` is being used, its ``default`` profile already installs the tool,
230 thus nothing needs to be done. If another profile is being used, the component
231 can be installed manually::
232
233 rustup component add clippy
234
235 The standalone installers also come with ``clippy``.
236
237
238 rustdoc
239 *******
240
241 ``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
242 documentation for Rust code (for details, please see
243 general-information.rst).
244
245 ``rustdoc`` is also used to test the examples provided in documented Rust code
246 (called doctests or documentation tests). The ``rusttest`` Make target uses
247 this feature.
248
249 If ``rustup`` is being used, all the profiles already install the tool,
250 thus nothing needs to be done.
251
252 The standalone installers also come with ``rustdoc``.
253
254
255 rust-analyzer
256 *************
257
258 The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
259 be used with many editors to enable syntax highlighting, completion, go to
260 definition, and other features.
261
262 ``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
263 can be generated by the ``rust-analyzer`` Make target::
264
265 make LLVM=1 rust-analyzer
266
267
268 Configuration
269 -------------
270
271 ``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
272 menu. The option is only shown if a suitable Rust toolchain is found (see
273 above), as long as the other requirements are met. In turn, this will make
274 visible the rest of options that depend on Rust.
275
276 Afterwards, go to::
277
278 Kernel hacking
279 -> Sample kernel code
280 -> Rust samples
281
282 And enable some sample modules either as built-in or as loadable.
283
284
285 Building
286 --------
287
288 Building a kernel with a complete LLVM toolchain is the best supported setup
289 at the moment. That is::
290
291 make LLVM=1
292
293 Using GCC also works for some configurations, but it is very experimental at
294 the moment.
295
296
297 Hacking
298 -------
299
300 To dive deeper, take a look at the source code of the samples
301 at ``samples/rust/``, the Rust support code under ``rust/`` and
302 the ``Rust hacking`` menu under ``Kernel hacking``.
303
304 If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
305 is the toolchain does not support Rust's new v0 mangling scheme yet.
306 There are a few ways out:
307
308 - Install a newer release (GDB >= 10.2, Binutils >= 2.36).
309
310 - Some versions of GDB (e.g. vanilla GDB 10.1) are able to use
311 the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``).
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.