库模块

Rust 库模块有两种类型:一种生成 Rust 库,另一种生成 C 兼容库。此外,对于构建系统来说,可将 Rust 过程宏 (proc-macros) 视为一种特殊类型的库。

rust_library

rust_library 模块会生成供其他 Rust 模块使用的 Rust 库。

除了 _host 变体外,Rust 库还有用于控制可用关联的模块类型。

Rust 库模块类型 定义
rust_library 提供两种库变体:rlibdylib。AOSP 推荐使用此模块类型的 Rust 库,因为它可以让模块在列为 rustlibs 属性下的依赖项时正常工作
rust_library_rlib 仅提供 Rust 库的 rlib 变体;仅提供 rlib 变体的模块不能保证可与 rustlibs 属性搭配使用。
rust_library_dylib 仅提供 Rust 库的 dylib 变体;仅提供 dylib 变体的模块不能保证可与 rustlibs 属性搭配使用。

rust_ffi

rust_ffi 模块会生成用于与 CC 模块互操作的 C 兼容库。

除了 _host 变体外,Rust FFI 库还有用于控制可用关联的模块类型,如下表所示。

Rust FFI 库模块类型 定义
rust_ffi 提供两种 C 库变体:静态库变体和共享库变体。
rust_ffi_shared 仅提供 C 共享库变体。
rust_ffi_static 仅提供 C 静态库变体。

如需查看使用 rust_ffi 从 C 调用 Rust 的基本示例,请参阅 Android Rust 模式页面。

如需了解更高级的用法,请访问官方 Rust 文档

rust_proc_macro

Rust 过程宏 (proc-macros) 可用于扩展编译器,以执行源代码转换或提供新属性。如需了解详情,请参阅 Rust 官方文档的过程宏页面。

对于构建系统来说,rust_proc_macro 模块的工作方式与 rust_library 模块类似。对于依赖于 rust_proc_macros 的模块,请将模块名称添加到 proc_macros 属性中。

由于 proc_macros 是编译器插件,它们必然是以主机为目标,而且不会生成任何会在设备上运行的代码。

重要的 Rust 库属性

除了适用于所有模块的重要的通用属性之外,还有下表中定义的一些属性。这些属性要么对 Rust 库模块特别重要,要么具有特定于 rust_library 模块类型的独有行为。

Rust 库属性 定义
stem/name stem 属性用于控制输出库文件名,此文件名原本默认为 name

Rust 编译器对库文件名规定了一些要求,因此构建系统会强制执行这些要求以避免出现编译问题。输出文件名必须符合 lib<crate_name><suffix> 格式。(此处有一个对 crate_name 属性的依赖项)。

crate_name 这是库生成的模块的必选属性;此外,它与输出文件名也存在关系。(请参阅 stem 定义。)
include_dirs 对于 rust_ffi 模块,此属性会定义一个字符串列表,列出表示相对包含路径的字符串。相对包含路径是包含相关 cc 模块可以使用的头文件的路径。

rust_library 或 rust_ffi 的关联

默认情况下,以设备为目标的 Rust 库模块始终动态关联到 libstd。但是,主机模块始终静态关联到 libstd

用于 rustlibs 依赖项的关联根据根模块的关联偏好设置而定。(例如,具有 prefer_rlib: true 设置的 rust_binary 所使用的 Rust 库变体将关联 rustlibs 作为 rlibs。)

为了允许生成不依赖于任何动态 Rust 库的根依赖项模块(例如静态可执行文件),rlibs 同时提供动态和静态 libstd 关联变体。Soong 会自动关联正确的变体。