Commit | Line | Data |
---|---|---|
d07479b2 MO |
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``). |