1.. SPDX-License-Identifier: GPL-2.0
2.. include:: ../disclaimer-zh_CN.rst
3
4:Original: Documentation/rust/quick-start.rst
5
6:翻译:
7
8 司延腾 Yanteng Si <siyanteng@loongson.cn>
9
10
11快速入门
12========
13
14本文介绍了如何开始使用Rust进行内核开发。
15
16
17构建依赖
18--------
19
20本节描述了如何获取构建所需的工具。
21
22其中一些依赖也许可以从Linux发行版中获得,包名可能是 ``rustc`` , ``rust-src`` ,
23``rust-bindgen`` 等。然而,在写这篇文章的时候,它们很可能还不够新,除非发行版跟踪最
24新的版本。
25
26为了方便检查是否满足要求,可以使用以下目标::
27
28	make LLVM=1 rustavailable
29
30这会触发与Kconfig用来确定是否应该启用 ``RUST_IS_AVAILABLE`` 相同的逻辑;不过,如
31果Kconfig认为不该启用,它会列出未满足的条件。
32
33
34rustc
35*****
36
37需要一个特定版本的Rust编译器。较新的版本可能会也可能不会工作,因为就目前而言,内核依赖
38于一些不稳定的Rust特性。
39
40如果使用的是 ``rustup`` ,请进入检出的源代码目录并运行::
41
42	rustup override set $(scripts/min-tool-version.sh rustc)
43
44或者从以下网址获取一个独立的安装程序或安装 ``rustup`` :
45
46	https://www.rust-lang.org
47
48
49Rust标准库源代码
50****************
51
52Rust标准库的源代码是必需的,因为构建系统会交叉编译 ``core`` 和 ``alloc`` 。
53
54如果正在使用 ``rustup`` ,请运行::
55
56	rustup component add rust-src
57
58这些组件是按工具链安装的,因此以后升级Rust编译器版本需要重新添加组件。
59
60否则,如果使用独立的安装程序,可以将Rust仓库克隆到工具链的安装文件夹中::
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在这种情况下,以后升级Rust编译器版本需要手动更新这个克隆的仓库。
68
69
70libclang
71********
72
73``bindgen`` 使用 ``libclang`` (LLVM的一部分)来理解内核中的C代码,这意味着需要安
74装LLVM;同在开启 ``CC=clang`` 或 ``LLVM=1`` 时编译内核一样。
75
76Linux发行版中可能会有合适的包,所以最好先检查一下。
77
78适用于部分系统和架构的二进制文件也可到以下网址下载:
79
80	https://releases.llvm.org/download.html
81
82或者自行构建LLVM,这需要相当长的时间,但并不是一个复杂的过程:
83
84	https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
85
86请参阅 Documentation/kbuild/llvm.rst 了解更多信息,以及获取预构建版本和发行包
87的进一步方法。
88
89
90bindgen
91*******
92
93内核的C端绑定是在构建时使用 ``bindgen`` 工具生成的。这需要特定的版本。
94
95通过以下方式安装它(注意,这将从源码下载并构建该工具)::
96
97	cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen
98
99
100开发依赖
101--------
102
103本节解释了如何获取开发所需的工具。也就是说,在构建内核时不需要这些工具。
104
105
106rustfmt
107*******
108
109``rustfmt`` 工具被用来自动格式化所有的Rust内核代码,包括生成的C绑定(详情请见
110coding-guidelines.rst )。
111
112如果使用的是 ``rustup`` ,它的 ``默认`` 配置文件已经安装了这个工具,因此不需要做什么。
113如果使用的是其他配置文件,可以手动安装该组件::
114
115	rustup component add rustfmt
116
117独立的安装程序也带有 ``rustfmt`` 。
118
119
120clippy
121******
122
123``clippy`` 是一个Rust linter。运行它可以为Rust代码提供额外的警告。它可以通过向 ``make``
124传递 ``CLIPPY=1`` 来运行(关于细节,详见 general-information.rst )。
125
126如果正在使用 ``rustup`` ,它的 ``默认`` 配置文件已经安装了这个工具,因此不需要做什么。
127如果使用的是另一个配置文件,该组件可以被手动安装::
128
129	rustup component add clippy
130
131独立的安装程序也带有 ``clippy`` 。
132
133
134cargo
135*****
136
137``cargo`` 是Rust的本地构建系统。目前需要它来运行测试,因为它被用来构建一个自定义的标准
138库,其中包含了内核中自定义 ``alloc`` 所提供的设施。测试可以使用 ``rusttest`` Make 目标
139来运行。
140
141如果使用的是 ``rustup`` ,所有的配置文件都已经安装了该工具,因此不需要再做什么。
142
143独立的安装程序也带有 ``cargo`` 。
144
145
146rustdoc
147*******
148
149``rustdoc`` 是Rust的文档工具。它为Rust代码生成漂亮的HTML文档(详情请见 general-information.rst )。
150
151``rustdoc`` 也被用来测试文档化的Rust代码中提供的例子(称为doctests或文档测试)。
152``rusttest`` 是本功能的Make目标。
153
154如果使用的是 ``rustup`` ,所有的配置文件都已经安装了这个工具,因此不需要做什么。
155
156独立的安装程序也带有 ``rustdoc`` 。
157
158
159rust-analyzer
160*************
161
162`rust-analyzer <https://rust-analyzer.github.io/>`_ 语言服务器可以和许多编辑器
163一起使用,以实现语法高亮、补全、转到定义和其他功能。
164
165``rust-analyzer`` 需要一个配置文件, ``rust-project.json``, 它可以由 ``rust-analyzer``
166Make 目标生成。
167
168
169配置
170----
171
172Rust支持(CONFIG_RUST)需要在 ``General setup`` 菜单中启用。在其他要求得到满足的情
173况下,该选项只有在找到合适的Rust工具链时才会显示(见上文)。相应的,这将使依赖Rust的其
174他选项可见。
175
176之后,进入::
177
178	Kernel hacking
179	    -> Sample kernel code
180	        -> Rust samples
181
182并启用一些内置或可加载的样例模块。
183
184
185构建
186----
187
188用完整的LLVM工具链构建内核是目前支持的最佳设置。即::
189
190	make LLVM=1
191
192对于不支持完整LLVM工具链的架构,使用::
193
194	make CC=clang
195
196使用GCC对某些配置也是可行的,但目前它是非常试验性的。
197
198
199折腾
200----
201
202要想深入了解,请看 ``samples/rust/`` 下的样例源代码、 ``rust/`` 下的Rust支持代码和
203``Kernel hacking`` 下的 ``Rust hacking`` 菜单。
204
205如果使用的是GDB/Binutils,而Rust符号没有被demangled,原因是工具链还不支持Rust的新v0
206mangling方案。有几个办法可以解决:
207
208  - 安装一个较新的版本(GDB >= 10.2, Binutils >= 2.36)。
209
210  - 一些版本的GDB(例如vanilla GDB 10.1)能够使用嵌入在调试信息(``CONFIG_DEBUG_INFO``)
211    中的pre-demangled的名字。
212