summaryrefslogtreecommitdiff
path: root/Documentation/translations/zh_CN/rust/quick-start.rst
blob: 8616556ae4d790a96aa9b78104b7512ca6914ebb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
.. SPDX-License-Identifier: GPL-2.0
.. include:: ../disclaimer-zh_CN.rst

:Original: Documentation/rust/quick-start.rst

:翻译:

 司延腾 Yanteng Si <siyanteng@loongson.cn>


快速入门
========

本文介绍了如何开始使用Rust进行内核开发。


构建依赖
--------

本节描述了如何获取构建所需的工具。

其中一些依赖也许可以从Linux发行版中获得,包名可能是 ``rustc`` , ``rust-src`` ,
``rust-bindgen`` 等。然而,在写这篇文章的时候,它们很可能还不够新,除非发行版跟踪最
新的版本。

为了方便检查是否满足要求,可以使用以下目标::

	make LLVM=1 rustavailable

这会触发与Kconfig用来确定是否应该启用 ``RUST_IS_AVAILABLE`` 相同的逻辑;不过,如
果Kconfig认为不该启用,它会列出未满足的条件。


rustc
*****

需要一个特定版本的Rust编译器。较新的版本可能会也可能不会工作,因为就目前而言,内核依赖
于一些不稳定的Rust特性。

如果使用的是 ``rustup`` ,请进入内核编译目录(或者用 ``--path=<build-dir>`` 参数
来 ``设置`` sub-command)并运行::

	rustup override set $(scripts/min-tool-version.sh rustc)

+这将配置你的工作目录使用正确版本的 ``rustc``,而不影响你的默认工具链。

请注意覆盖应用当前的工作目录(和它的子目录)。

如果你使用 ``rustup``, 可以从下面的链接拉取一个单独的安装程序:

	https://forge.rust-lang.org/infra/other-installation-methods.html#standalone


Rust标准库源代码
****************

Rust标准库的源代码是必需的,因为构建系统会交叉编译 ``core````alloc`` 。

如果正在使用 ``rustup`` ,请运行::

	rustup component add rust-src

这些组件是按工具链安装的,因此以后升级Rust编译器版本需要重新添加组件。

否则,如果使用独立的安装程序,可以将Rust源码树下载到安装工具链的文件夹中::

       curl -L "https://static.rust-lang.org/dist/rust-src-$(scripts/min-tool-version.sh rustc).tar.gz" |
               tar -xzf - -C "$(rustc --print sysroot)/lib" \
               "rust-src-$(scripts/min-tool-version.sh rustc)/rust-src/lib/" \
               --strip-components=3

在这种情况下,以后升级Rust编译器版本需要手动更新这个源代码树(这可以通过移除
``$(rustc --print sysroot)/lib/rustlib/src/rust`` ,然后重新执行上
面的命令做到)。


libclang
********

``bindgen`` 使用 ``libclang`` (LLVM的一部分)来理解内核中的C代码,这意味着需要安
装LLVM;同在开启``LLVM=1`` 时编译内核一样。

Linux发行版中可能会有合适的包,所以最好先检查一下。

适用于部分系统和架构的二进制文件也可到以下网址下载:

	https://releases.llvm.org/download.html

或者自行构建LLVM,这需要相当长的时间,但并不是一个复杂的过程:

	https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm

请参阅 Documentation/kbuild/llvm.rst 了解更多信息,以及获取预构建版本和发行包
的进一步方法。


bindgen
*******

内核的C端绑定是在构建时使用 ``bindgen`` 工具生成的。这需要特定的版本。

通过以下方式安装它(注意,这将从源码下载并构建该工具)::

	cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen-cli

``bindgen`` 需要找到合适的 ``libclang`` 才能工作。如果没有找到(或者找到的
``libclang`` 与应该使用的 ``libclang`` 不同),则可以使用 ``clang-sys``
理解的环境变量(Rust绑定创建的 ``bindgen`` 用来访问 ``libclang``):


* ``LLVM_CONFIG_PATH`` 可以指向一个 ``llvm-config`` 可执行文件。

* 或者 ``LIBCLANG_PATH`` 可以指向 ``libclang`` 共享库或包含它的目录。

* 或者 ``CLANG_PATH`` 可以指向 ``clang`` 可执行文件。

详情请参阅 ``clang-sys`` 的文档:


开发依赖
--------

本节解释了如何获取开发所需的工具。也就是说,在构建内核时不需要这些工具。


rustfmt
*******

``rustfmt`` 工具被用来自动格式化所有的Rust内核代码,包括生成的C绑定(详情请见
coding-guidelines.rst )。

如果使用的是 ``rustup`` ,它的 ``默认`` 配置文件已经安装了这个工具,因此不需要做什么。
如果使用的是其他配置文件,可以手动安装该组件::

	rustup component add rustfmt

独立的安装程序也带有 ``rustfmt``clippy
******

``clippy`` 是一个Rust linter。运行它可以为Rust代码提供额外的警告。它可以通过向 ``make``
传递 ``CLIPPY=1`` 来运行(关于细节,详见 general-information.rst )。

如果正在使用 ``rustup`` ,它的 ``默认`` 配置文件已经安装了这个工具,因此不需要做什么。
如果使用的是另一个配置文件,该组件可以被手动安装::

	rustup component add clippy

独立的安装程序也带有 ``clippy``cargo
*****

``cargo`` 是Rust的本地构建系统。目前需要它来运行测试,因为它被用来构建一个自定义的标准
库,其中包含了内核中自定义 ``alloc`` 所提供的设施。测试可以使用 ``rusttest`` Make 目标
来运行。

如果使用的是 ``rustup`` ,所有的配置文件都已经安装了该工具,因此不需要再做什么。

独立的安装程序也带有 ``cargo``rustdoc
*******

``rustdoc`` 是Rust的文档工具。它为Rust代码生成漂亮的HTML文档(详情请见 general-information.rst )。

``rustdoc`` 也被用来测试文档化的Rust代码中提供的例子(称为doctests或文档测试)。
``rusttest`` 是本功能的Make目标。

如果使用的是 ``rustup`` ,所有的配置文件都已经安装了这个工具,因此不需要做什么。

独立的安装程序也带有 ``rustdoc``rust-analyzer
*************

`rust-analyzer <https://rust-analyzer.github.io/>`_ 语言服务器可以和许多编辑器
一起使用,以实现语法高亮、补全、转到定义和其他功能。

``rust-analyzer`` 需要一个配置文件, ``rust-project.json``, 它可以由 ``rust-analyzer``
Make 目标生成::

       make LLVM=1 rust-analyzer


配置
----

Rust支持(CONFIG_RUST)需要在 ``General setup`` 菜单中启用。在其他要求得到满足的情
况下,该选项只有在找到合适的Rust工具链时才会显示(见上文)。相应的,这将使依赖Rust的其
他选项可见。

之后,进入::

	Kernel hacking
	    -> Sample kernel code
	        -> Rust samples

并启用一些内置或可加载的样例模块。


构建
----

用完整的LLVM工具链构建内核是目前支持的最佳设置。即::

	make LLVM=1

使用GCC对某些配置也是可行的,但目前它是非常试验性的。


折腾
----

要想深入了解,请看 ``samples/rust/`` 下的样例源代码、 ``rust/`` 下的Rust支持代码和
``Kernel hacking`` 下的 ``Rust hacking`` 菜单。

如果使用的是GDB/Binutils,而Rust符号没有被demangled,原因是工具链还不支持Rust的新v0
mangling方案。有几个办法可以解决:

  - 安装一个较新的版本(GDB >= 10.2, Binutils >= 2.36)。

  - 一些版本的GDB(例如vanilla GDB 10.1)能够使用嵌入在调试信息(``CONFIG_DEBUG_INFO``)
    中的pre-demangled的名字。