projects/linux·blob master · refs

354 lines · 10.4 KiB

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 13 (Trixie), as well as Testing and Debian Unstable (Sid) provide recent
43Rust 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 provides recent Rust releases and thus it should generally work out
61of 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 provides recent Rust releases and thus it should generally work out of the
72box, 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 rust-src rust-bindgen clang
88
89
90Ubuntu
91******
92
93Ubuntu 26.04 LTS provides recent Rust releases and thus it should
94generally work out of the box, e.g.::
95
96 apt install rustc rust-src bindgen rustfmt rust-clippy
97
98In addition, ``RUST_LIB_SRC`` needs to be set, e.g.::
99
100 RUST_LIB_SRC=/usr/src/rustc-$(rustc --version | cut -d' ' -f2)/library
101
102For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
103
104
10524.04 LTS and older
106~~~~~~~~~~~~~~~~~~~
107
108Though Ubuntu 24.04 LTS and older versions still provide recent Rust
109releases, they require some additional configuration to be set, using
110the versioned packages, e.g.::
111
112 apt install rustc-1.85 rust-1.85-src bindgen-0.71 rustfmt-1.85 \
113 rust-1.85-clippy
114 ln -s /usr/lib/rust-1.85/bin/rustfmt /usr/bin/rustfmt-1.85
115 ln -s /usr/lib/rust-1.85/bin/clippy-driver /usr/bin/clippy-driver-1.85
116
117None of these packages set their tools as defaults; therefore they should be
118specified explicitly, e.g.::
119
120 make LLVM=1 RUSTC=rustc-1.85 RUSTDOC=rustdoc-1.85 RUSTFMT=rustfmt-1.85 \
121 CLIPPY_DRIVER=clippy-driver-1.85 BINDGEN=bindgen-0.71
122
123Alternatively, modify the ``PATH`` variable to place the Rust 1.85 binaries
124first and set ``bindgen`` as the default, e.g.::
125
126 PATH=/usr/lib/rust-1.85/bin:$PATH
127 update-alternatives --install /usr/bin/bindgen bindgen \
128 /usr/bin/bindgen-0.71 100
129 update-alternatives --set bindgen /usr/bin/bindgen-0.71
130
131``RUST_LIB_SRC`` may need to be set when using the versioned packages, e.g.::
132
133 RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.85 --version | cut -d' ' -f2)/library
134
135For convenience, ``RUST_LIB_SRC`` can be exported to the global environment.
136
137In addition, ``bindgen-0.71`` is available in newer releases (24.04 LTS),
138but it may not be available in older ones (20.04 LTS and 22.04 LTS),
139thus ``bindgen`` may need to be built manually (please see below).
140
141
142Requirements: Building
143----------------------
144
145This section explains how to fetch the tools needed for building.
146
147To easily check whether the requirements are met, the following target
148can be used::
149
150 make LLVM=1 rustavailable
151
152This triggers the same logic used by Kconfig to determine whether
153``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not
154if that is the case.
155
156
157rustc
158*****
159
160A recent version of the Rust compiler is required.
161
162If ``rustup`` is being used, enter the kernel build directory (or use
163``--path=<build-dir>`` argument to the ``set`` sub-command) and run,
164for instance::
165
166 rustup override set stable
167
168This will configure your working directory to use the given version of
169``rustc`` without affecting your default toolchain.
170
171Note that the override applies to the current working directory (and its
172sub-directories).
173
174If you are not using ``rustup``, fetch a standalone installer from:
175
176 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
177
178
179Rust standard library source
180****************************
181
182The Rust standard library source is required because the build system will
183cross-compile ``core``.
184
185If ``rustup`` is being used, run::
186
187 rustup component add rust-src
188
189The components are installed per toolchain, thus upgrading the Rust compiler
190version later on requires re-adding the component.
191
192Otherwise, if a standalone installer is used, the Rust source tree may be
193downloaded into the toolchain's installation folder::
194
195 curl -L "https://static.rust-lang.org/dist/rust-src-$(rustc --version | cut -d' ' -f2).tar.gz" |
196 tar -xzf - -C "$(rustc --print sysroot)/lib" \
197 "rust-src-$(rustc --version | cut -d' ' -f2)/rust-src/lib/" \
198 --strip-components=3
199
200In this case, upgrading the Rust compiler version later on requires manually
201updating the source tree (this can be done by removing ``$(rustc --print
202sysroot)/lib/rustlib/src/rust`` then rerunning the above command).
203
204
205libclang
206********
207
208``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
209in the kernel, which means LLVM needs to be installed; like when the kernel
210is compiled with ``LLVM=1``.
211
212Linux distributions are likely to have a suitable one available, so it is
213best to check that first.
214
215There are also some binaries for several systems and architectures uploaded at:
216
217 https://releases.llvm.org/download.html
218
219Otherwise, building LLVM takes quite a while, but it is not a complex process:
220
221 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
222
223Please see Documentation/kbuild/llvm.rst for more information and further ways
224to fetch pre-built releases and distribution packages.
225
226
227bindgen
228*******
229
230The bindings to the C side of the kernel are generated at build time using
231the ``bindgen`` tool.
232
233Install it, for instance, via (note that this will download and build the tool
234from source)::
235
236 cargo install --locked bindgen-cli
237
238``bindgen`` uses the ``clang-sys`` crate to find a suitable ``libclang`` (which
239may be linked statically, dynamically or loaded at runtime). By default, the
240``cargo`` command above will produce a ``bindgen`` binary that will load
241``libclang`` at runtime. If it is not found (or a different ``libclang`` than
242the one found should be used), the process can be tweaked, e.g. by using the
243``LIBCLANG_PATH`` environment variable. For details, please see ``clang-sys``'s
244documentation at:
245
246 https://github.com/KyleMayes/clang-sys#linking
247
248 https://github.com/KyleMayes/clang-sys#environment-variables
249
250
251Requirements: Developing
252------------------------
253
254This section explains how to fetch the tools needed for developing. That is,
255they are not needed when just building the kernel.
256
257
258rustfmt
259*******
260
261The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
262including the generated C bindings (for details, please see
263coding-guidelines.rst).
264
265If ``rustup`` is being used, its ``default`` profile already installs the tool,
266thus nothing needs to be done. If another profile is being used, the component
267can be installed manually::
268
269 rustup component add rustfmt
270
271The standalone installers also come with ``rustfmt``.
272
273
274clippy
275******
276
277``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
278It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
279general-information.rst).
280
281If ``rustup`` is being used, its ``default`` profile already installs the tool,
282thus nothing needs to be done. If another profile is being used, the component
283can be installed manually::
284
285 rustup component add clippy
286
287The standalone installers also come with ``clippy``.
288
289
290rustdoc
291*******
292
293``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
294documentation for Rust code (for details, please see
295general-information.rst).
296
297``rustdoc`` is also used to test the examples provided in documented Rust code
298(called doctests or documentation tests). The ``rusttest`` Make target uses
299this feature.
300
301If ``rustup`` is being used, all the profiles already install the tool,
302thus nothing needs to be done.
303
304The standalone installers also come with ``rustdoc``.
305
306
307rust-analyzer
308*************
309
310The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
311be used with many editors to enable syntax highlighting, completion, go to
312definition, and other features.
313
314``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
315can be generated by the ``rust-analyzer`` Make target::
316
317 make LLVM=1 rust-analyzer
318
319
320Configuration
321-------------
322
323``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
324menu. The option is only shown if a suitable Rust toolchain is found (see
325above), as long as the other requirements are met. In turn, this will make
326visible the rest of options that depend on Rust.
327
328Afterwards, go to::
329
330 Kernel hacking
331 -> Sample kernel code
332 -> Rust samples
333
334And enable some sample modules either as built-in or as loadable.
335
336
337Building
338--------
339
340Building a kernel with a complete LLVM toolchain is the best supported setup
341at the moment. That is::
342
343 make LLVM=1
344
345Using GCC also works for some configurations, but it is very experimental at
346the moment.
347
348
349Hacking
350-------
351
352To dive deeper, take a look at the source code of the samples
353at ``samples/rust/``, the Rust support code under ``rust/`` and
354the ``Rust hacking`` menu under ``Kernel hacking``.