Android Rust 模块

作为一般原则， rust_*模块定义严格遵守cc_*的使用和期望。以下是 Rust 二进制文件的模块定义示例：

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

本页介绍了rust_*模块最常见的属性。有关特定模块类型和示例模块定义的更多信息，请参阅二进制模块、库模块或测试模块页面。

基本模块类型

类型定义想要查询更多的信息
rust_binary Rust 二进制文件二进制模块页面
rust_library生成一个 Rust 库，并提供rlib和dylib变体。 rust_library ，库模块页面。
rust_ffi生成可供 cc 模块使用的 Rust C 库，并提供静态和共享变体。 rust_ffi ，库模块页面
rust_proc_macro生成一个proc-macro Rust 库。 （这些类似于编译器插件。） rust_proc_macro ，库模块页面
rust_test生成使用标准 Rust 测试工具的 Rust 测试二进制文件。测试模块页面
rust_fuzz利用libfuzzer生成 Rust 模糊二进制文件。 rust_fuzz模块示例
rust_protobuf生成源代码并生成一个为特定 protobuf 提供接口的 Rust 库。 Protobufs 模块和源代码生成器页面
rust_bindgen生成源代码并生成一个 Rust 库，其中包含与 C 库的 Rust 绑定。 Bindgen 绑定模块和源生成器页面

重要的共同属性

这些属性在所有 Android Rust 模块中都很常见。与各个 Rust 模块相关的任何其他（唯一）属性都列在该模块的页面上。

名称

name是您的模块的名称。与其他 Soong 模块一样，这在大多数Android.bp模块类型中必须是唯一的。默认情况下， name用作输出文件名。如果输出文件名必须与模块名不同，请使用stem属性来定义它。

干

stem （可选）提供对输出文件名的直接控制（不包括文件扩展名和其他后缀）。例如，具有rust_library_rlib libfoo会生成一个libfoo.rlib文件。如果不为stem属性提供值，则输出文件名默认采用模块名称。

当您无法将模块名称设置为所需的输出文件名时，请使用stem函数。例如， log箱的rust_library被命名为liblog_rust ，因为liblog cc_library已经存在。在这种情况下使用stem属性可确保输出文件名为liblog.*而不是liblog_rust.* 。

源文件

srcs包含一个代表模块入口点的源文件（通常是main.rs或lib.rs ）。 rustc处理编译所需的所有其他源文件的解析和发现，这些在生成的deps文件中枚举。

如果可能，请避免在平台代码中使用这种用法；有关更多信息，请参阅源生成器。

箱子名称

crate_name通过rustc --crate_name标志设置 crate 名称元数据。对于生成库的模块，这必须与源中使用的预期 crate 名称匹配。例如，如果模块libfoo_bar在源代码中被引用为extern crate foo_bar ，那么它必须是crate_name: "foo_bar" 。

这个属性对所有rust_*模块都是通用的，但它是生成 Rust 库的模块所必需的（例如rust_library 、 rust_ffi 、 rust_bindgen 、 rust_protobuf和rust_proc_macro ）。这些模块对crate_name和输出文件名之间的关系强制执行rustc要求。有关详细信息，请参阅库模块部分。

皮棉

rustc linter默认为除源生成器之外的所有模块类型运行。定义了一些 lint 集并用于验证模块源。此类 lint 集的可能值如下：

  • default （默认的 lints 集，取决于模块的位置）
  • android （适用于所有 Android 平台代码的最严格的 lint 集）
  • vendor （适用于供应商代码的一组宽松的 lint）
  • none （用于忽略所有 lint 警告和错误）

clippy_lints

默认情况下，除了源生成器之外，所有模块类型都会运行clippy linter 。定义了几组用于验证模块源的 lint。这些是一些可能的值：

  • default （取决于模块位置的默认 lint 集）
  • android （适用于所有 Android 平台代码的最严格的 lint 集）
  • vendor （适用于供应商代码的一组宽松的 lint）
  • none （用于忽略所有 lint 警告和错误）

版

edition定义了用于编译此代码的 Rust 版本。这类似于 C 和 C++ 的标准版本。有效值为2015和2018 （默认值）。

旗帜

flags包含在编译期间传递给rustc的标志的字符串列表。

ld_flags

ld-flags包含在编译源代码时传递给链接器的标志字符串列表。这些是由-C linker-args rustc 标志传递的。 clang用作链接器前端，调用lld进行实际链接。

特征

features是在编译期间必须启用的功能的字符串列表。这通过--cfg 'feature="foo"'传递给 rustc。大多数功能都是附加的，因此在许多情况下，这包括所有依赖模块所需的完整功能集。但是，在功能相互排斥的情况下，请在任何提供冲突功能的构建文件中定义其他模块。

配置文件

cfgs包含要在编译期间启用的cfg标志的字符串列表。这由--cfg foo和--cfg "fizz=buzz"传递给rustc 。

构建系统会在特定情况下自动设置某些cfg标志，如下所列：

  • 作为 dylib 构建的模块将设置android_dylib cfg。
  • 将使用 VNDK 的模块将设置android_vndk cfg。这类似于 C++ 的__ANDROID_VNDK__定义。

条

strip控制是否以及如何剥离输出文件（如果适用）。如果未设置，设备模块默认剥离除 mini debuginfo 之外的所有内容。默认情况下，主机模块不剥离任何符号。有效值包括none以禁用剥离，以及all以剥离所有内容，包括 mini debuginfo。其他值可以在Soong 模块参考中找到。

主机支持

对于设备模块， host_supported参数指示模块是否还应提供主机变体。

定义库依赖项

Rust 模块可以通过以下属性同时依赖 CC 和 Rust 库：

属性名称描述
rustlibs同样是依赖项的rust_library模块列表。将此作为您声明依赖项的首选方法，因为它允许构建系统选择首选链接。 （请参阅下面的链接 Rust 库时）
rlibs必须静态链接为rlibs的rust_library模块列表。 （谨慎使用；请参阅下面的与 Rust 库链接时。）
dylibs要动态链接为dylibs的rust_library模块列表。 （谨慎使用；请参阅下面的与 Rust 库链接时。）
shared_libs必须作为共享库动态链接的cc_library模块列表。
static_libs必须作为静态库静态链接的cc_library模块列表。
whole_static_libs cc_library模块的列表，这些模块应该作为静态库静态地着墨并包含在生成的库中。对于rust_ffi_static变体， whole_static_libraries将包含在生成的静态库存档中。对于rust_library_rlib变体， whole_static_libraries库将被捆绑到生成的rlib库中。

在链接 Rust 库时，作为最佳实践，使用rustlibs属性而不是rlibs或dylibs这样做，除非你有特定的理由这样做。这允许构建系统根据根模块的要求选择正确的链接，并减少依赖关系树包含库的rlib和dylib版本的机会（这将导致编译失败）。

不受支持和有限的支持构建功能

Soong 的 Rust 对vendor和vendor_ramdisk映像和快照提供有限的支持。但是， staticlibs 、 cdylibs 、 rlibs和binaries 。对于供应商映像构建目标，设置了android_vndk cfg属性。如果系统目标和供应商目标之间存在差异，您可以在代码中使用它。 rust_proc_macros不会作为供应商快照的一部分被捕获；如果依赖这些，请确保对它们进行适当的版本控制。

不支持产品、VNDK 和恢复映像。

增量构建

开发人员可以通过将SOONG_RUSTC_INCREMENTAL环境变量设置为true来启用 Rust 源代码的增量编译。

警告：这不能保证生成与 buildbots 生成的二进制文件相同的二进制文件。目标文件中包含的函数或数据的地址可能不同。为确保生成的工件与 EngProd 基础架构构建的工件 100% 相同，请不要设置此值。