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``).

  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 kernel build directory (or use
 37``--path=<build-dir>`` argument to the ``set`` sub-command) and run::
 38
 39	rustup override set $(scripts/min-tool-version.sh rustc)
 40
 41This will configure your working directory to use the correct version of
 42``rustc`` without affecting your default toolchain.
 43
 44Note that the override applies to the current working directory (and its
 45sub-directories).
 46
 47If you are not using ``rustup``, fetch a standalone installer from:
 48
 49	https://forge.rust-lang.org/infra/other-installation-methods.html#standalone
 50
 51
 52Rust standard library source
 53****************************
 54
 55The Rust standard library source is required because the build system will
 56cross-compile ``core`` and ``alloc``.
 57
 58If ``rustup`` is being used, run::
 59
 60	rustup component add rust-src
 61
 62The components are installed per toolchain, thus upgrading the Rust compiler
 63version later on requires re-adding the component.
 64
 65Otherwise, if a standalone installer is used, the Rust source tree may be
 66downloaded into the toolchain's installation folder::
 67
 68	curl -L "https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz" |
 69		tar -xzf - -C "$(rustc --print sysroot)/lib" \
 70		"rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/" \
 71		--strip-components=3
 72
 73In this case, upgrading the Rust compiler version later on requires manually
 74updating the source tree (this can be done by removing ``$(rustc --print
 75sysroot)/lib/rustlib/src/rust`` then rerunning the above command).
 76
 77
 78libclang
 79********
 80
 81``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
 82in the kernel, which means LLVM needs to be installed; like when the kernel
 83is compiled with ``LLVM=1``.
 84
 85Linux distributions are likely to have a suitable one available, so it is
 86best to check that first.
 87
 88There are also some binaries for several systems and architectures uploaded at:
 89
 90	https://releases.llvm.org/download.html
 91
 92Otherwise, building LLVM takes quite a while, but it is not a complex process:
 93
 94	https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
 95
 96Please see Documentation/kbuild/llvm.rst for more information and further ways
 97to fetch pre-built releases and distribution packages.
 98
 99
100bindgen
101*******
102
103The bindings to the C side of the kernel are generated at build time using
104the ``bindgen`` tool. A particular version is required.
105
106Install it via (note that this will download and build the tool from source)::
107
108	cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli
109
110``bindgen`` needs to find a suitable ``libclang`` in order to work. If it is
111not found (or a different ``libclang`` than the one found should be used),
112the process can be tweaked using the environment variables understood by
113``clang-sys`` (the Rust bindings crate that ``bindgen`` uses to access
114``libclang``):
115
116* ``LLVM_CONFIG_PATH`` can be pointed to an ``llvm-config`` executable.
117
118* Or ``LIBCLANG_PATH`` can be pointed to a ``libclang`` shared library
119  or to the directory containing it.
120
121* Or ``CLANG_PATH`` can be pointed to a ``clang`` executable.
122
123For details, please see ``clang-sys``'s documentation at:
124
125	https://github.com/KyleMayes/clang-sys#environment-variables
126
127
128Requirements: Developing
129------------------------
130
131This section explains how to fetch the tools needed for developing. That is,
132they are not needed when just building the kernel.
133
134
135rustfmt
136*******
137
138The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
139including the generated C bindings (for details, please see
140coding-guidelines.rst).
141
142If ``rustup`` is being used, its ``default`` profile already installs the tool,
143thus nothing needs to be done. If another profile is being used, the component
144can be installed manually::
145
146	rustup component add rustfmt
147
148The standalone installers also come with ``rustfmt``.
149
150
151clippy
152******
153
154``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
155It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
156general-information.rst).
157
158If ``rustup`` is being used, its ``default`` profile already installs the tool,
159thus nothing needs to be done. If another profile is being used, the component
160can be installed manually::
161
162	rustup component add clippy
163
164The standalone installers also come with ``clippy``.
165
166
167cargo
168*****
169
170``cargo`` is the Rust native build system. It is currently required to run
171the tests since it is used to build a custom standard library that contains
172the facilities provided by the custom ``alloc`` in the kernel. The tests can
173be run using the ``rusttest`` Make target.
174
175If ``rustup`` is being used, all the profiles already install the tool,
176thus nothing needs to be done.
177
178The standalone installers also come with ``cargo``.
179
180
181rustdoc
182*******
183
184``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
185documentation for Rust code (for details, please see
186general-information.rst).
187
188``rustdoc`` is also used to test the examples provided in documented Rust code
189(called doctests or documentation tests). The ``rusttest`` Make target uses
190this feature.
191
192If ``rustup`` is being used, all the profiles already install the tool,
193thus nothing needs to be done.
194
195The standalone installers also come with ``rustdoc``.
196
197
198rust-analyzer
199*************
200
201The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
202be used with many editors to enable syntax highlighting, completion, go to
203definition, and other features.
204
205``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
206can be generated by the ``rust-analyzer`` Make target::
207
208	make LLVM=1 rust-analyzer
209
210
211Configuration
212-------------
213
214``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
215menu. The option is only shown if a suitable Rust toolchain is found (see
216above), as long as the other requirements are met. In turn, this will make
217visible the rest of options that depend on Rust.
218
219Afterwards, go to::
220
221	Kernel hacking
222	    -> Sample kernel code
223	        -> Rust samples
224
225And enable some sample modules either as built-in or as loadable.
226
227
228Building
229--------
230
231Building a kernel with a complete LLVM toolchain is the best supported setup
232at the moment. That is::
233
234	make LLVM=1
 
 
 
 
235
236Using GCC also works for some configurations, but it is very experimental at
237the moment.
238
239
240Hacking
241-------
242
243To dive deeper, take a look at the source code of the samples
244at ``samples/rust/``, the Rust support code under ``rust/`` and
245the ``Rust hacking`` menu under ``Kernel hacking``.
246
247If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
248is the toolchain does not support Rust's new v0 mangling scheme yet.
249There are a few ways out:
250
251  - Install a newer release (GDB >= 10.2, Binutils >= 2.36).
252
253  - Some versions of GDB (e.g. vanilla GDB 10.1) are able to use
254    the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``).