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 库,并提供rlibdylib变体。 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.rslib.rs )。 rustc处理编译所需的所有其他源文件的解析和发现,这些在生成的deps文件中枚举。

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

箱子名称

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

这个属性对所有rust_*模块都是通用的,但它是生成 Rust 库的模块所必需的(例如rust_libraryrust_ffirust_bindgenrust_protobufrust_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++ 的标准版本。有效值为20152018 (默认值)。

旗帜

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必须静态链接为rlibsrust_library模块列表。 (谨慎使用;请参阅下面的与 Rust 库链接时。)
dylibs要动态链接为dylibsrust_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属性而不是rlibsdylibs这样做,除非你有特定的理由这样做。这允许构建系统根据根模块的要求选择正确的链接,并减少依赖关系树包含库的rlibdylib版本的机会(这将导致编译失败)。

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

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

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

增量构建

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

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