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安装内核开发所需的 Rust 工具链有几种方式。一种简单的方式是使用 Linux 发行版的软件包 17（如果它们合适的话）——下面的第一节解释了这种方法。这种方法的一个优势是，通常发行版会 18匹配 Rust 和 Clang 所使用的 LLVM。 19 20另一种方式是使用 `kernel.org <https://kernel.org/pub/tools/llvm/rust/>`_ 上提 21供的预构建稳定版本的 LLVM+Rust。这些与 :ref:`获取 LLVM <zh_cn_getting_llvm>` 中的精 22简快速 LLVM 工具链相同，并添加了 Rust for Linux 支持的 Rust 版本。提供了两套工具 23链："最新 LLVM" 和 "匹配 LLVM"（请参阅链接了解更多信息）。 24 25或者，接下来的两个 "依赖" 章节将解释每个组件以及如何通过 ``rustup``、Rust 的独立 26安装程序或从源码构建来安装它们。 27 28本文档的其余部分解释了有关如何入门的其他方面。 29 30 31发行版 32------ 33 34Arch Linux 35********** 36 37Arch Linux 提供较新的 Rust 版本，因此通常开箱即用，例如:: 38 39 pacman -S rust rust-src rust-bindgen 40 41 42Debian 43****** 44 45Debian 13（Trixie）以及 Testing 和 Debian Unstable（Sid）提供较新的 Rust 版 46本，因此通常开箱即用，例如:: 47 48 apt install rustc rust-src bindgen rustfmt rust-clippy 49 50 51Fedora Linux 52************ 53 54Fedora Linux 提供较新的 Rust 版本，因此通常开箱即用，例如:: 55 56 dnf install rust rust-src bindgen-cli rustfmt clippy 57 58 59Gentoo Linux 60************ 61 62Gentoo Linux 提供较新的 Rust 版本，因此通常开箱即用， 63例如:: 64 65 USE='rust-src rustfmt clippy' emerge dev-lang/rust dev-util/bindgen 66 67可能需要设置 ``LIBCLANG_PATH``。 68 69 70Nix 71*** 72 73Nix 提供较新的 Rust 版本，因此通常开箱即用，例如:: 74 75 { pkgs ? import <nixpkgs> {} }: 76 pkgs.mkShell { 77 nativeBuildInputs = with pkgs; [ rustc rust-bindgen rustfmt clippy ]; 78 RUST_LIB_SRC = "${pkgs.rust.packages.stable.rustPlatform.rustLibSrc}"; 79 } 80 81 82openSUSE 83******** 84 85openSUSE Slowroll 和 openSUSE Tumbleweed 提供较新的 Rust 版本，因此通常开箱 86即用，例如:: 87 88 zypper install rust rust-src rust-bindgen clang 89 90 91Ubuntu 92****** 93 94Ubuntu 25.10 和 26.04 LTS 提供较新的 Rust 版本，因此通常开箱即用， 95例如:: 96 97 apt install rustc rust-src bindgen rustfmt rust-clippy 98 99此外，需要设置 ``RUST_LIB_SRC``，例如:: 100 101 RUST_LIB_SRC=/usr/src/rustc-$(rustc --version | cut -d' ' -f2)/library 102 103为方便起见，可以将 ``RUST_LIB_SRC`` 导出到全局环境中。 104 105 10624.04 LTS 及更早版本 107~~~~~~~~~~~~~~~~~~~~ 108 109虽然 Ubuntu 24.04 LTS 及更早版本仍然提供较新的 Rust 版本，但它们需要一些额外的配 110置，使用带版本号的软件包，例如:: 111 112 apt install rustc-1.85 rust-1.85-src bindgen-0.71 rustfmt-1.85 \ 113 rust-1.85-clippy 114 ln -s /usr/lib/rust-1.85/bin/rustfmt /usr/bin/rustfmt-1.85 115 ln -s /usr/lib/rust-1.85/bin/clippy-driver /usr/bin/clippy-driver-1.85 116 117这些软件包都不会将其工具设置为默认值；因此应该显式指定它们，例如:: 118 119 make LLVM=1 RUSTC=rustc-1.85 RUSTDOC=rustdoc-1.85 RUSTFMT=rustfmt-1.85 \ 120 CLIPPY_DRIVER=clippy-driver-1.85 BINDGEN=bindgen-0.71 121 122或者，修改 ``PATH`` 变量将 Rust 1.85 的二进制文件放在前面，并将 ``bindgen`` 设 123置为默认值，例如:: 124 125 PATH=/usr/lib/rust-1.85/bin:$PATH 126 update-alternatives --install /usr/bin/bindgen bindgen \ 127 /usr/bin/bindgen-0.71 100 128 update-alternatives --set bindgen /usr/bin/bindgen-0.71 129 130使用带版本号的软件包时可能需要设置 ``RUST_LIB_SRC``，例如:: 131 132 RUST_LIB_SRC=/usr/src/rustc-$(rustc-1.85 --version | cut -d' ' -f2)/library 133 134为方便起见，可以将 ``RUST_LIB_SRC`` 导出到全局环境中。 135 136此外， ``bindgen-0.71`` 在较新的版本（24.04 LTS）中可用，但在更早的版本 137（20.04 LTS 和 22.04 LTS）中可能不可用，因此可能需要手动构建 ``bindgen`` 138（请参见下文）。 139 140 141构建依赖 142-------- 143 144本节描述了如何获取构建所需的工具。 145 146为了方便检查是否满足要求，可以使用以下目标:: 147 148 make LLVM=1 rustavailable 149 150这会触发与Kconfig用来确定是否应该启用 ``RUST_IS_AVAILABLE`` 相同的逻辑；不过，如 151果Kconfig认为不该启用，它会列出未满足的条件。 152 153 154rustc 155***** 156 157需要一个较新版本的Rust编译器。 158 159如果使用的是 ``rustup`` ，请进入内核编译目录（或者用 ``--path=<build-dir>`` 参数 160来 ``设置`` sub-command)，例如运行:: 161 162 rustup override set stable 163 164这将配置你的工作目录使用给定版本的 ``rustc``，而不影响你的默认工具链。 165 166请注意覆盖应用当前的工作目录（和它的子目录）。 167 168如果你使用 ``rustup``， 可以从下面的链接拉取一个单独的安装程序: 169 170 https://forge.rust-lang.org/infra/other-installation-methods.html#standalone 171 172 173Rust标准库源代码 174**************** 175 176Rust标准库的源代码是必需的，因为构建系统会交叉编译 ``core`` 。 177 178如果正在使用 ``rustup`` ，请运行:: 179 180 rustup component add rust-src 181 182这些组件是按工具链安装的，因此以后升级Rust编译器版本需要重新添加组件。 183 184否则，如果使用独立的安装程序，可以将Rust源码树下载到安装工具链的文件夹中:: 185 186 curl -L "https://static.rust-lang.org/dist/rust-src-$(rustc --version | cut -d' ' -f2).tar.gz" | 187 tar -xzf - -C "$(rustc --print sysroot)/lib" \ 188 "rust-src-$(rustc --version | cut -d' ' -f2)/rust-src/lib/" \ 189 --strip-components=3 190 191在这种情况下，以后升级Rust编译器版本需要手动更新这个源代码树（这可以通过移除 192``$(rustc --print sysroot)/lib/rustlib/src/rust`` ，然后重新执行上 193面的命令做到）。 194 195 196libclang 197******** 198 199``bindgen`` 使用 ``libclang`` （LLVM的一部分）来理解内核中的C代码，这意味着需要安 200装LLVM；同在开启``LLVM=1`` 时编译内核一样。 201 202Linux发行版中可能会有合适的包，所以最好先检查一下。 203 204适用于部分系统和架构的二进制文件也可到以下网址下载： 205 206 https://releases.llvm.org/download.html 207 208或者自行构建LLVM，这需要相当长的时间，但并不是一个复杂的过程： 209 210 https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm 211 212请参阅 Documentation/kbuild/llvm.rst 了解更多信息，以及获取预构建版本和发行包 213的进一步方法。 214 215 216bindgen 217******* 218 219内核的C端绑定是在构建时使用 ``bindgen`` 工具生成的。 220 221例如，通过以下方式安装它（注意，这将从源码下载并构建该工具）:: 222 223 cargo install --locked bindgen-cli 224 225``bindgen`` 使用 ``clang-sys`` crate 来查找合适的 ``libclang`` （可以静态链 226接、动态链接或在运行时加载）。默认情况下，上面的 ``cargo`` 命令会生成一个在运行时 227加载 ``libclang`` 的 ``bindgen`` 二进制文件。如果没有找到（或者应该使用与找到的 228不同的 ``libclang``），可以调整该过程，例如使用 ``LIBCLANG_PATH`` 环境变量。详 229情请参阅 ``clang-sys`` 的文档： 230 231 https://github.com/KyleMayes/clang-sys#linking 232 233 https://github.com/KyleMayes/clang-sys#environment-variables 234 235 236开发依赖 237-------- 238 239本节解释了如何获取开发所需的工具。也就是说，在构建内核时不需要这些工具。 240 241 242rustfmt 243******* 244 245``rustfmt`` 工具被用来自动格式化所有的Rust内核代码，包括生成的C绑定（详情请见 246coding-guidelines.rst ）。 247 248如果使用的是 ``rustup`` ，它的 ``默认`` 配置文件已经安装了这个工具，因此不需要做什么。 249如果使用的是其他配置文件，可以手动安装该组件:: 250 251 rustup component add rustfmt 252 253独立的安装程序也带有 ``rustfmt`` 。 254 255 256clippy 257****** 258 259``clippy`` 是一个Rust linter。运行它可以为Rust代码提供额外的警告。它可以通过向 ``make`` 260传递 ``CLIPPY=1`` 来运行（关于细节，详见 general-information.rst ）。 261 262如果正在使用 ``rustup`` ，它的 ``默认`` 配置文件已经安装了这个工具，因此不需要做什么。 263如果使用的是另一个配置文件，该组件可以被手动安装:: 264 265 rustup component add clippy 266 267独立的安装程序也带有 ``clippy`` 。 268 269 270rustdoc 271******* 272 273``rustdoc`` 是Rust的文档工具。它为Rust代码生成漂亮的HTML文档（详情请见 general-information.rst ）。 274 275``rustdoc`` 也被用来测试文档化的Rust代码中提供的例子（称为doctests或文档测试）。 276``rusttest`` 是本功能的Make目标。 277 278如果使用的是 ``rustup`` ，所有的配置文件都已经安装了这个工具，因此不需要做什么。 279 280独立的安装程序也带有 ``rustdoc`` 。 281 282 283rust-analyzer 284************* 285 286`rust-analyzer <https://rust-analyzer.github.io/>`_ 语言服务器可以和许多编辑器 287一起使用，以实现语法高亮、补全、转到定义和其他功能。 288 289``rust-analyzer`` 需要一个配置文件， ``rust-project.json``, 它可以由 ``rust-analyzer`` 290Make 目标生成:: 291 292 make LLVM=1 rust-analyzer 293 294 295配置 296---- 297 298Rust支持（CONFIG_RUST）需要在 ``General setup`` 菜单中启用。在其他要求得到满足的情 299况下，该选项只有在找到合适的Rust工具链时才会显示（见上文）。相应的，这将使依赖Rust的其 300他选项可见。 301 302之后，进入:: 303 304 Kernel hacking 305 -> Sample kernel code 306 -> Rust samples 307 308并启用一些内置或可加载的样例模块。 309 310 311构建 312---- 313 314用完整的LLVM工具链构建内核是目前支持的最佳设置。即:: 315 316 make LLVM=1 317 318使用GCC对某些配置也是可行的，但目前它是非常试验性的。 319 320 321折腾 322---- 323 324要想深入了解，请看 ``samples/rust/`` 下的样例源代码、 ``rust/`` 下的Rust支持代码和 325``Kernel hacking`` 下的 ``Rust hacking`` 菜单。 326