Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: add Rust documentation
Most of the documentation for Rust is written within the source code
itself, as it is idiomatic for Rust projects. This applies to both
the shared infrastructure at `rust/` as well as any other Rust module
(e.g. drivers) written across the kernel.
However, these documents contain general information that does not
fit particularly well in the source code, like the Quick Start guide.
It also contains a few other small changes elsewhere in the
documentation folder.
Reviewed-by: Kees Cook <keescook@chromium.org>
Co-developed-by: Alex Gaynor <alex.gaynor@gmail.com>
Signed-off-by: Alex Gaynor <alex.gaynor@gmail.com>
Co-developed-by: Finn Behrens <me@kloenk.de>
Signed-off-by: Finn Behrens <me@kloenk.de>
Co-developed-by: Adam Bratschi-Kaye <ark.email@gmail.com>
Signed-off-by: Adam Bratschi-Kaye <ark.email@gmail.com>
Co-developed-by: Wedson Almeida Filho <wedsonaf@google.com>
Signed-off-by: Wedson Almeida Filho <wedsonaf@google.com>
Co-developed-by: Michael Ellerman <mpe@ellerman.id.au>
Signed-off-by: Michael Ellerman <mpe@ellerman.id.au>
Co-developed-by: Sven Van Asbroeck <thesven73@gmail.com>
Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com>
Co-developed-by: Wu XiangCheng <bobwxc@email.cn>
Signed-off-by: Wu XiangCheng <bobwxc@email.cn>
Co-developed-by: Gary Guo <gary@garyguo.net>
Signed-off-by: Gary Guo <gary@garyguo.net>
Co-developed-by: Boris-Chengbiao Zhou <bobo1239@web.de>
Signed-off-by: Boris-Chengbiao Zhou <bobo1239@web.de>
Co-developed-by: Yuki Okushi <jtitor@2k36.org>
Signed-off-by: Yuki Okushi <jtitor@2k36.org>
Co-developed-by: Wei Liu <wei.liu@kernel.org>
Signed-off-by: Wei Liu <wei.liu@kernel.org>
Co-developed-by: Daniel Xu <dxu@dxuuu.xyz>
Signed-off-by: Daniel Xu <dxu@dxuuu.xyz>
Co-developed-by: Julian Merkle <me@jvmerkle.de>
Signed-off-by: Julian Merkle <me@jvmerkle.de>
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
+675
-4
+3
Documentation/doc-guide/kernel-doc.rst
+3
Documentation/doc-guide/kernel-doc.rst
···
14
14
reasons. The kernel source contains tens of thousands of kernel-doc
15
15
comments. Please stick to the style described here.
16
16
17
+
.. note:: kernel-doc does not cover Rust code: please see
18
+
Documentation/rust/general-information.rst instead.
19
+
17
20
The kernel-doc structure is extracted from the comments, and proper
18
21
`Sphinx C Domain`_ function and type descriptions with anchors are
19
22
generated from them. The descriptions are filtered for special kernel-doc
+1
Documentation/index.rst
+1
Documentation/index.rst
+17
Documentation/kbuild/kbuild.rst
+17
Documentation/kbuild/kbuild.rst
···
48
48
-------
49
49
Additional options to the C compiler (for built-in and modules).
50
50
51
+
KRUSTFLAGS
52
+
----------
53
+
Additional options to the Rust compiler (for built-in and modules).
54
+
51
55
CFLAGS_KERNEL
52
56
-------------
53
57
Additional options for $(CC) when used to compile
···
60
56
CFLAGS_MODULE
61
57
-------------
62
58
Additional module specific options to use for $(CC).
59
+
60
+
RUSTFLAGS_KERNEL
61
+
----------------
62
+
Additional options for $(RUSTC) when used to compile
63
+
code that is compiled as built-in.
64
+
65
+
RUSTFLAGS_MODULE
66
+
----------------
67
+
Additional module specific options to use for $(RUSTC).
63
68
64
69
LDFLAGS_MODULE
65
70
--------------
···
81
68
HOSTCXXFLAGS
82
69
------------
83
70
Additional flags to be passed to $(HOSTCXX) when building host programs.
71
+
72
+
HOSTRUSTFLAGS
73
+
-------------
74
+
Additional flags to be passed to $(HOSTRUSTC) when building host programs.
84
75
85
76
HOSTLDFLAGS
86
77
-----------
+46
-4
Documentation/kbuild/makefiles.rst
+46
-4
Documentation/kbuild/makefiles.rst
···
29
29
--- 4.1 Simple Host Program
30
30
--- 4.2 Composite Host Programs
31
31
--- 4.3 Using C++ for host programs
32
-
--- 4.4 Controlling compiler options for host programs
33
-
--- 4.5 When host programs are actually built
32
+
--- 4.4 Using Rust for host programs
33
+
--- 4.5 Controlling compiler options for host programs
34
+
--- 4.6 When host programs are actually built
34
35
35
36
=== 5 Userspace Program support
36
37
--- 5.1 Simple Userspace Program
···
836
835
qconf-cxxobjs := qconf.o
837
836
qconf-objs := check.o
838
837
839
-
4.4 Controlling compiler options for host programs
838
+
4.4 Using Rust for host programs
839
+
--------------------------------
840
+
841
+
Kbuild offers support for host programs written in Rust. However,
842
+
since a Rust toolchain is not mandatory for kernel compilation,
843
+
it may only be used in scenarios where Rust is required to be
844
+
available (e.g. when ``CONFIG_RUST`` is enabled).
845
+
846
+
Example::
847
+
848
+
hostprogs := target
849
+
target-rust := y
850
+
851
+
Kbuild will compile ``target`` using ``target.rs`` as the crate root,
852
+
located in the same directory as the ``Makefile``. The crate may
853
+
consist of several source files (see ``samples/rust/hostprogs``).
854
+
855
+
4.5 Controlling compiler options for host programs
840
856
--------------------------------------------------
841
857
842
858
When compiling host programs, it is possible to set specific flags.
···
885
867
When linking qconf, it will be passed the extra option
886
868
"-L$(QTDIR)/lib".
887
869
888
-
4.5 When host programs are actually built
870
+
4.6 When host programs are actually built
889
871
-----------------------------------------
890
872
891
873
Kbuild will only build host-programs when they are referenced
···
1199
1181
The first example utilises the trick that a config option expands
1200
1182
to 'y' when selected.
1201
1183
1184
+
KBUILD_RUSTFLAGS
1185
+
$(RUSTC) compiler flags
1186
+
1187
+
Default value - see top level Makefile
1188
+
Append or modify as required per architecture.
1189
+
1190
+
Often, the KBUILD_RUSTFLAGS variable depends on the configuration.
1191
+
1192
+
Note that target specification file generation (for ``--target``)
1193
+
is handled in ``scripts/generate_rust_target.rs``.
1194
+
1202
1195
KBUILD_AFLAGS_KERNEL
1203
1196
Assembler options specific for built-in
1204
1197
···
1236
1207
$(KBUILD_CFLAGS_MODULE) is used to add arch-specific options that
1237
1208
are used for $(CC).
1238
1209
From commandline CFLAGS_MODULE shall be used (see kbuild.rst).
1210
+
1211
+
KBUILD_RUSTFLAGS_KERNEL
1212
+
$(RUSTC) options specific for built-in
1213
+
1214
+
$(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to
1215
+
compile resident kernel code.
1216
+
1217
+
KBUILD_RUSTFLAGS_MODULE
1218
+
Options for $(RUSTC) when building modules
1219
+
1220
+
$(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that
1221
+
are used for $(RUSTC).
1222
+
From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).
1239
1223
1240
1224
KBUILD_LDFLAGS_MODULE
1241
1225
Options for $(LD) when linking modules
+41
Documentation/process/changes.rst
+41
Documentation/process/changes.rst
···
31
31
====================== =============== ========================================
32
32
GNU C 5.1 gcc --version
33
33
Clang/LLVM (optional) 11.0.0 clang --version
34
+
Rust (optional) 1.62.0 rustc --version
35
+
bindgen (optional) 0.56.0 bindgen --version
34
36
GNU make 3.81 make --version
35
37
bash 4.2 bash --version
36
38
binutils 2.23 ld -v
···
81
79
kernels. Older releases aren't guaranteed to work, and we may drop workarounds
82
80
from the kernel that were used to support older versions. Please see additional
83
81
docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
82
+
83
+
Rust (optional)
84
+
---------------
85
+
86
+
A particular version of the Rust toolchain is required. Newer versions may or
87
+
may not work because the kernel depends on some unstable Rust features, for
88
+
the moment.
89
+
90
+
Each Rust toolchain comes with several "components", some of which are required
91
+
(like ``rustc``) and some that are optional. The ``rust-src`` component (which
92
+
is optional) needs to be installed to build the kernel. Other components are
93
+
useful for developing.
94
+
95
+
Please see Documentation/rust/quick-start.rst for instructions on how to
96
+
satisfy the build requirements of Rust support. In particular, the ``Makefile``
97
+
target ``rustavailable`` is useful to check why the Rust toolchain may not
98
+
be detected.
99
+
100
+
bindgen (optional)
101
+
------------------
102
+
103
+
``bindgen`` is used to generate the Rust bindings to the C side of the kernel.
104
+
It depends on ``libclang``.
84
105
85
106
Make
86
107
----
···
373
348
Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>`
374
349
for details about Sphinx requirements.
375
350
351
+
rustdoc
352
+
-------
353
+
354
+
``rustdoc`` is used to generate the documentation for Rust code. Please see
355
+
Documentation/rust/general-information.rst for more information.
356
+
376
357
Getting updated software
377
358
========================
378
359
···
394
363
----------
395
364
396
365
- :ref:`Getting LLVM <getting_llvm>`.
366
+
367
+
Rust
368
+
----
369
+
370
+
- Documentation/rust/quick-start.rst.
371
+
372
+
bindgen
373
+
-------
374
+
375
+
- Documentation/rust/quick-start.rst.
397
376
398
377
Make
399
378
----
+18
Documentation/rust/arch-support.rst
+18
Documentation/rust/arch-support.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
Arch Support
4
+
============
5
+
6
+
Currently, the Rust compiler (``rustc``) uses LLVM for code generation,
7
+
which limits the supported architectures that can be targeted. In addition,
8
+
support for building the kernel with LLVM/Clang varies (please see
9
+
Documentation/kbuild/llvm.rst). This support is needed for ``bindgen``
10
+
which uses ``libclang``.
11
+
12
+
Below is a general summary of architectures that currently work. Level of
13
+
support corresponds to ``S`` values in the ``MAINTAINERS`` file.
14
+
15
+
============ ================ ==============================================
16
+
Architecture Level of support Constraints
17
+
============ ================ ==============================================
18
+
============ ================ ==============================================
+216
Documentation/rust/coding-guidelines.rst
+216
Documentation/rust/coding-guidelines.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
Coding Guidelines
4
+
=================
5
+
6
+
This document describes how to write Rust code in the kernel.
7
+
8
+
9
+
Style & formatting
10
+
------------------
11
+
12
+
The code should be formatted using ``rustfmt``. In this way, a person
13
+
contributing from time to time to the kernel does not need to learn and
14
+
remember one more style guide. More importantly, reviewers and maintainers
15
+
do not need to spend time pointing out style issues anymore, and thus
16
+
less patch roundtrips may be needed to land a change.
17
+
18
+
.. note:: Conventions on comments and documentation are not checked by
19
+
``rustfmt``. Thus those are still needed to be taken care of.
20
+
21
+
The default settings of ``rustfmt`` are used. This means the idiomatic Rust
22
+
style is followed. For instance, 4 spaces are used for indentation rather
23
+
than tabs.
24
+
25
+
It is convenient to instruct editors/IDEs to format while typing,
26
+
when saving or at commit time. However, if for some reason reformatting
27
+
the entire kernel Rust sources is needed at some point, the following can be
28
+
run::
29
+
30
+
make LLVM=1 rustfmt
31
+
32
+
It is also possible to check if everything is formatted (printing a diff
33
+
otherwise), for instance for a CI, with::
34
+
35
+
make LLVM=1 rustfmtcheck
36
+
37
+
Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
38
+
individual files, and does not require a kernel configuration. Sometimes it may
39
+
even work with broken code.
40
+
41
+
42
+
Comments
43
+
--------
44
+
45
+
"Normal" comments (i.e. ``//``, rather than code documentation which starts
46
+
with ``///`` or ``//!``) are written in Markdown the same way as documentation
47
+
comments are, even though they will not be rendered. This improves consistency,
48
+
simplifies the rules and allows to move content between the two kinds of
49
+
comments more easily. For instance:
50
+
51
+
.. code-block:: rust
52
+
53
+
// `object` is ready to be handled now.
54
+
f(object);
55
+
56
+
Furthermore, just like documentation, comments are capitalized at the beginning
57
+
of a sentence and ended with a period (even if it is a single sentence). This
58
+
includes ``// SAFETY:``, ``// TODO:`` and other "tagged" comments, e.g.:
59
+
60
+
.. code-block:: rust
61
+
62
+
// FIXME: The error should be handled properly.
63
+
64
+
Comments should not be used for documentation purposes: comments are intended
65
+
for implementation details, not users. This distinction is useful even if the
66
+
reader of the source file is both an implementor and a user of an API. In fact,
67
+
sometimes it is useful to use both comments and documentation at the same time.
68
+
For instance, for a ``TODO`` list or to comment on the documentation itself.
69
+
For the latter case, comments can be inserted in the middle; that is, closer to
70
+
the line of documentation to be commented. For any other case, comments are
71
+
written after the documentation, e.g.:
72
+
73
+
.. code-block:: rust
74
+
75
+
/// Returns a new [`Foo`].
76
+
///
77
+
/// # Examples
78
+
///
79
+
// TODO: Find a better example.
80
+
/// ```
81
+
/// let foo = f(42);
82
+
/// ```
83
+
// FIXME: Use fallible approach.
84
+
pub fn f(x: i32) -> Foo {
85
+
// ...
86
+
}
87
+
88
+
One special kind of comments are the ``// SAFETY:`` comments. These must appear
89
+
before every ``unsafe`` block, and they explain why the code inside the block is
90
+
correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:
91
+
92
+
.. code-block:: rust
93
+
94
+
// SAFETY: `p` is valid by the safety requirements.
95
+
unsafe { *p = 0; }
96
+
97
+
``// SAFETY:`` comments are not to be confused with the ``# Safety`` sections
98
+
in code documentation. ``# Safety`` sections specify the contract that callers
99
+
(for functions) or implementors (for traits) need to abide by. ``// SAFETY:``
100
+
comments show why a call (for functions) or implementation (for traits) actually
101
+
respects the preconditions stated in a ``# Safety`` section or the language
102
+
reference.
103
+
104
+
105
+
Code documentation
106
+
------------------
107
+
108
+
Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
109
+
Instead, the usual system for documenting Rust code is used: the ``rustdoc``
110
+
tool, which uses Markdown (a lightweight markup language).
111
+
112
+
To learn Markdown, there are many guides available out there. For instance,
113
+
the one at:
114
+
115
+
https://commonmark.org/help/
116
+
117
+
This is how a well-documented Rust function may look like:
118
+
119
+
.. code-block:: rust
120
+
121
+
/// Returns the contained [`Some`] value, consuming the `self` value,
122
+
/// without checking that the value is not [`None`].
123
+
///
124
+
/// # Safety
125
+
///
126
+
/// Calling this method on [`None`] is *[undefined behavior]*.
127
+
///
128
+
/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
129
+
///
130
+
/// # Examples
131
+
///
132
+
/// ```
133
+
/// let x = Some("air");
134
+
/// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
135
+
/// ```
136
+
pub unsafe fn unwrap_unchecked(self) -> T {
137
+
match self {
138
+
Some(val) => val,
139
+
140
+
// SAFETY: The safety contract must be upheld by the caller.
141
+
None => unsafe { hint::unreachable_unchecked() },
142
+
}
143
+
}
144
+
145
+
This example showcases a few ``rustdoc`` features and some conventions followed
146
+
in the kernel:
147
+
148
+
- The first paragraph must be a single sentence briefly describing what
149
+
the documented item does. Further explanations must go in extra paragraphs.
150
+
151
+
- Unsafe functions must document their safety preconditions under
152
+
a ``# Safety`` section.
153
+
154
+
- While not shown here, if a function may panic, the conditions under which
155
+
that happens must be described under a ``# Panics`` section.
156
+
157
+
Please note that panicking should be very rare and used only with a good
158
+
reason. In almost all cases, a fallible approach should be used, typically
159
+
returning a ``Result``.
160
+
161
+
- If providing examples of usage would help readers, they must be written in
162
+
a section called ``# Examples``.
163
+
164
+
- Rust items (functions, types, constants...) must be linked appropriately
165
+
(``rustdoc`` will create a link automatically).
166
+
167
+
- Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment
168
+
describing why the code inside is sound.
169
+
170
+
While sometimes the reason might look trivial and therefore unneeded,
171
+
writing these comments is not just a good way of documenting what has been
172
+
taken into account, but most importantly, it provides a way to know that
173
+
there are no *extra* implicit constraints.
174
+
175
+
To learn more about how to write documentation for Rust and extra features,
176
+
please take a look at the ``rustdoc`` book at:
177
+
178
+
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
179
+
180
+
181
+
Naming
182
+
------
183
+
184
+
Rust kernel code follows the usual Rust naming conventions:
185
+
186
+
https://rust-lang.github.io/api-guidelines/naming.html
187
+
188
+
When existing C concepts (e.g. macros, functions, objects...) are wrapped into
189
+
a Rust abstraction, a name as close as reasonably possible to the C side should
190
+
be used in order to avoid confusion and to improve readability when switching
191
+
back and forth between the C and Rust sides. For instance, macros such as
192
+
``pr_info`` from C are named the same in the Rust side.
193
+
194
+
Having said that, casing should be adjusted to follow the Rust naming
195
+
conventions, and namespacing introduced by modules and types should not be
196
+
repeated in the item names. For instance, when wrapping constants like:
197
+
198
+
.. code-block:: c
199
+
200
+
#define GPIO_LINE_DIRECTION_IN 0
201
+
#define GPIO_LINE_DIRECTION_OUT 1
202
+
203
+
The equivalent in Rust may look like (ignoring documentation):
204
+
205
+
.. code-block:: rust
206
+
207
+
pub mod gpio {
208
+
pub enum LineDirection {
209
+
In = bindings::GPIO_LINE_DIRECTION_IN as _,
210
+
Out = bindings::GPIO_LINE_DIRECTION_OUT as _,
211
+
}
212
+
}
213
+
214
+
That is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as
215
+
``gpio::LineDirection::In``. In particular, it should not be named
216
+
``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``.
+79
Documentation/rust/general-information.rst
+79
Documentation/rust/general-information.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
General Information
4
+
===================
5
+
6
+
This document contains useful information to know when working with
7
+
the Rust support in the kernel.
8
+
9
+
10
+
Code documentation
11
+
------------------
12
+
13
+
Rust kernel code is documented using ``rustdoc``, its built-in documentation
14
+
generator.
15
+
16
+
The generated HTML docs include integrated search, linked items (e.g. types,
17
+
functions, constants), source code, etc. They may be read at (TODO: link when
18
+
in mainline and generated alongside the rest of the documentation):
19
+
20
+
http://kernel.org/
21
+
22
+
The docs can also be easily generated and read locally. This is quite fast
23
+
(same order as compiling the code itself) and no special tools or environment
24
+
are needed. This has the added advantage that they will be tailored to
25
+
the particular kernel configuration used. To generate them, use the ``rustdoc``
26
+
target with the same invocation used for compilation, e.g.::
27
+
28
+
make LLVM=1 rustdoc
29
+
30
+
To read the docs locally in your web browser, run e.g.::
31
+
32
+
xdg-open rust/doc/kernel/index.html
33
+
34
+
To learn about how to write the documentation, please see coding-guidelines.rst.
35
+
36
+
37
+
Extra lints
38
+
-----------
39
+
40
+
While ``rustc`` is a very helpful compiler, some extra lints and analyses are
41
+
available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to
42
+
the same invocation used for compilation, e.g.::
43
+
44
+
make LLVM=1 CLIPPY=1
45
+
46
+
Please note that Clippy may change code generation, thus it should not be
47
+
enabled while building a production kernel.
48
+
49
+
50
+
Abstractions vs. bindings
51
+
-------------------------
52
+
53
+
Abstractions are Rust code wrapping kernel functionality from the C side.
54
+
55
+
In order to use functions and types from the C side, bindings are created.
56
+
Bindings are the declarations for Rust of those functions and types from
57
+
the C side.
58
+
59
+
For instance, one may write a ``Mutex`` abstraction in Rust which wraps
60
+
a ``struct mutex`` from the C side and calls its functions through the bindings.
61
+
62
+
Abstractions are not available for all the kernel internal APIs and concepts,
63
+
but it is intended that coverage is expanded as time goes on. "Leaf" modules
64
+
(e.g. drivers) should not use the C bindings directly. Instead, subsystems
65
+
should provide as-safe-as-possible abstractions as needed.
66
+
67
+
68
+
Conditional compilation
69
+
-----------------------
70
+
71
+
Rust code has access to conditional compilation based on the kernel
72
+
configuration:
73
+
74
+
.. code-block:: rust
75
+
76
+
#[cfg(CONFIG_X)] // Enabled (`y` or `m`)
77
+
#[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)
78
+
#[cfg(CONFIG_X="m")] // Enabled as a module (`m`)
79
+
#[cfg(not(CONFIG_X))] // Disabled
+22
Documentation/rust/index.rst
+22
Documentation/rust/index.rst
···
1
+
.. SPDX-License-Identifier: GPL-2.0
2
+
3
+
Rust
4
+
====
5
+
6
+
Documentation related to Rust within the kernel. To start using Rust
7
+
in the kernel, please read the quick-start.rst guide.
8
+
9
+
.. toctree::
10
+
:maxdepth: 1
11
+
12
+
quick-start
13
+
general-information
14
+
coding-guidelines
15
+
arch-support
16
+
17
+
.. only:: subproject and html
18
+
19
+
Indices
20
+
=======
21
+
22
+
* :ref:`genindex`
+232
Documentation/rust/quick-start.rst
+232
Documentation/rust/quick-start.rst
···
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
+
9
+
Requirements: Building
10
+
----------------------
11
+
12
+
This section explains how to fetch the tools needed for building.
13
+
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.
18
+
19
+
To easily check whether the requirements are met, the following target
20
+
can be used::
21
+
22
+
make LLVM=1 rustavailable
23
+
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
26
+
if that is the case.
27
+
28
+
29
+
rustc
30
+
*****
31
+
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
34
+
Rust features.
35
+
36
+
If ``rustup`` is being used, enter the checked out source code directory
37
+
and run::
38
+
39
+
rustup override set $(scripts/min-tool-version.sh rustc)
40
+
41
+
Otherwise, fetch a standalone installer or install ``rustup`` from:
42
+
43
+
https://www.rust-lang.org
44
+
45
+
46
+
Rust standard library source
47
+
****************************
48
+
49
+
The Rust standard library source is required because the build system will
50
+
cross-compile ``core`` and ``alloc``.
51
+
52
+
If ``rustup`` is being used, run::
53
+
54
+
rustup component add rust-src
55
+
56
+
The components are installed per toolchain, thus upgrading the Rust compiler
57
+
version later on requires re-adding the component.
58
+
59
+
Otherwise, if a standalone installer is used, the Rust repository may be cloned
60
+
into 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
+
67
+
In this case, upgrading the Rust compiler version later on requires manually
68
+
updating this clone.
69
+
70
+
71
+
libclang
72
+
********
73
+
74
+
``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
75
+
in the kernel, which means LLVM needs to be installed; like when the kernel
76
+
is compiled with ``CC=clang`` or ``LLVM=1``.
77
+
78
+
Linux distributions are likely to have a suitable one available, so it is
79
+
best to check that first.
80
+
81
+
There are also some binaries for several systems and architectures uploaded at:
82
+
83
+
https://releases.llvm.org/download.html
84
+
85
+
Otherwise, 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
+
89
+
Please see Documentation/kbuild/llvm.rst for more information and further ways
90
+
to fetch pre-built releases and distribution packages.
91
+
92
+
93
+
bindgen
94
+
*******
95
+
96
+
The bindings to the C side of the kernel are generated at build time using
97
+
the ``bindgen`` tool. A particular version is required.
98
+
99
+
Install 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
+
104
+
Requirements: Developing
105
+
------------------------
106
+
107
+
This section explains how to fetch the tools needed for developing. That is,
108
+
they are not needed when just building the kernel.
109
+
110
+
111
+
rustfmt
112
+
*******
113
+
114
+
The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
115
+
including the generated C bindings (for details, please see
116
+
coding-guidelines.rst).
117
+
118
+
If ``rustup`` is being used, its ``default`` profile already installs the tool,
119
+
thus nothing needs to be done. If another profile is being used, the component
120
+
can be installed manually::
121
+
122
+
rustup component add rustfmt
123
+
124
+
The standalone installers also come with ``rustfmt``.
125
+
126
+
127
+
clippy
128
+
******
129
+
130
+
``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
131
+
It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
132
+
general-information.rst).
133
+
134
+
If ``rustup`` is being used, its ``default`` profile already installs the tool,
135
+
thus nothing needs to be done. If another profile is being used, the component
136
+
can be installed manually::
137
+
138
+
rustup component add clippy
139
+
140
+
The standalone installers also come with ``clippy``.
141
+
142
+
143
+
cargo
144
+
*****
145
+
146
+
``cargo`` is the Rust native build system. It is currently required to run
147
+
the tests since it is used to build a custom standard library that contains
148
+
the facilities provided by the custom ``alloc`` in the kernel. The tests can
149
+
be run using the ``rusttest`` Make target.
150
+
151
+
If ``rustup`` is being used, all the profiles already install the tool,
152
+
thus nothing needs to be done.
153
+
154
+
The standalone installers also come with ``cargo``.
155
+
156
+
157
+
rustdoc
158
+
*******
159
+
160
+
``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
161
+
documentation for Rust code (for details, please see
162
+
general-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
166
+
this feature.
167
+
168
+
If ``rustup`` is being used, all the profiles already install the tool,
169
+
thus nothing needs to be done.
170
+
171
+
The standalone installers also come with ``rustdoc``.
172
+
173
+
174
+
rust-analyzer
175
+
*************
176
+
177
+
The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
178
+
be used with many editors to enable syntax highlighting, completion, go to
179
+
definition, and other features.
180
+
181
+
``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
182
+
can be generated by the ``rust-analyzer`` Make target.
183
+
184
+
185
+
Configuration
186
+
-------------
187
+
188
+
``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
189
+
menu. The option is only shown if a suitable Rust toolchain is found (see
190
+
above), as long as the other requirements are met. In turn, this will make
191
+
visible the rest of options that depend on Rust.
192
+
193
+
Afterwards, go to::
194
+
195
+
Kernel hacking
196
+
-> Sample kernel code
197
+
-> Rust samples
198
+
199
+
And enable some sample modules either as built-in or as loadable.
200
+
201
+
202
+
Building
203
+
--------
204
+
205
+
Building a kernel with a complete LLVM toolchain is the best supported setup
206
+
at the moment. That is::
207
+
208
+
make LLVM=1
209
+
210
+
For architectures that do not support a full LLVM toolchain, use::
211
+
212
+
make CC=clang
213
+
214
+
Using GCC also works for some configurations, but it is very experimental at
215
+
the moment.
216
+
217
+
218
+
Hacking
219
+
-------
220
+
221
+
To dive deeper, take a look at the source code of the samples
222
+
at ``samples/rust/``, the Rust support code under ``rust/`` and
223
+
the ``Rust hacking`` menu under ``Kernel hacking``.
224
+
225
+
If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
226
+
is the toolchain does not support Rust's new v0 mangling scheme yet.
227
+
There 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``).