rust/quick-start.rst

   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
  34 rustc
  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
  49 Rust标准库源代码
  50 ****************
  51
  52 Rust标准库的源代码是必需的，因为构建系统会交叉编译 ``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
  70 libclang
  71 ********
  72
  73 ``bindgen`` 使用 ``libclang`` （LLVM的一部分）来理解内核中的C代码，这意味着需要安
  74 装LLVM；同在开启 ``CC=clang`` 或 ``LLVM=1`` 时编译内核一样。
  75
  76 Linux发行版中可能会有合适的包，所以最好先检查一下。
  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
  90 bindgen
  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
 106 rustfmt
 107 *******
 108
 109 ``rustfmt`` 工具被用来自动格式化所有的Rust内核代码，包括生成的C绑定（详情请见
 110 coding-guidelines.rst ）。
 111
 112 如果使用的是 ``rustup`` ，它的 ``默认`` 配置文件已经安装了这个工具，因此不需要做什么。
 113 如果使用的是其他配置文件，可以手动安装该组件::
 114
 115         rustup component add rustfmt
 116
 117 独立的安装程序也带有 ``rustfmt`` 。
 118
 119
 120 clippy
 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
 134 cargo
 135 *****
 136
 137 ``cargo`` 是Rust的本地构建系统。目前需要它来运行测试，因为它被用来构建一个自定义的标准
 138 库，其中包含了内核中自定义 ``alloc`` 所提供的设施。测试可以使用 ``rusttest`` Make 目标
 139 来运行。
 140
 141 如果使用的是 ``rustup`` ，所有的配置文件都已经安装了该工具，因此不需要再做什么。
 142
 143 独立的安装程序也带有 ``cargo`` 。
 144
 145
 146 rustdoc
 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
 159 rust-analyzer
 160 *************
 161
 162 `rust-analyzer <https://rust-analyzer.github.io/>`_ 语言服务器可以和许多编辑器
 163 一起使用，以实现语法高亮、补全、转到定义和其他功能。
 164
 165 ``rust-analyzer`` 需要一个配置文件， ``rust-project.json``, 它可以由 ``rust-analyzer``
 166 Make 目标生成。
 167
 168
 169 配置
 170 ----
 171
 172 Rust支持（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
 206 mangling方案。有几个办法可以解决：
 207
 208   - 安装一个较新的版本（GDB >= 10.2, Binutils >= 2.36）。
 209
 210   - 一些版本的GDB（例如vanilla GDB 10.1）能够使用嵌入在调试信息(``CONFIG_DEBUG_INFO``)
 211     中的pre-demangled的名字。