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