基础知识¶

格式化 Rust 代码¶

要格式化目录 $DIR 中的所有 Rust 代码，请运行

./mach lint -l rustfmt --fix $DIR

许多 Cargo 命令可以在单个 crate 上运行。切换到包含 crate 的 Cargo.toml 文件的目录，然后在设置适当的 MOZ_TOPOBJDIR 后运行命令。例如，要为 xpcom crate 生成并查看 rustdocs，请运行以下命令

cd xpcom/rust/xpcom
MOZ_TOPOBJDIR=$OBJDIR cargo doc
cd -
firefox target/doc/xpcom/index.html

其中 $OBJDIR 是目标目录的路径。

可以轻松地从 Rust 代码访问静态布尔/整数偏好设置。在 modules/libpref/init/StaticPrefList.yaml 中的偏好设置定义中添加一个 rust: true 字段，如下所示

- name: my.lucky.pref
  type: RelaxedAtomicBool
  value: true
  mirror: always
  rust: true

然后可以通过 pref! 宏访问该偏好设置，如下所示

let my_lucky_pref = static_prefs::pref!("my.lucky.pref");

以下树内辅助 crate 为一些常见模式提供了惯用的支持。

nserror 将 nsresult 代码反映到 Rust 中。
nsstring 公开了 XPCOM 字符串类型的绑定。您可以使用与 C++ 相同的 ns{A,C}String 类型来表示已分配的字符串，并在边界之间传递它们。还有 ns{A,C}Str 用于依赖或借用的字符串。
thin-vec 提供了一个与 Gecko 的 nsTArray 布局兼容的类似 Rust Vec 的类型。
xpcom 为组件的实现提供了多个构建块。
- RefPtr 类型用于管理引用计数指针。
- XPCOM 组件 getter 由 xpcom/components/gen_static_components.py 生成，可以这样调用
```
use xpcom::{interfaces::nsIPrefService, RefPtr};
let pref_service: RefPtr<nsIPrefService> = xpcom::components::Preferences::service()?;
```
- 还有一个 get_service 函数，它与 C++ 中的 do_GetService 类似，作为替代方案。
- 一组 derive 宏有助于声明接口实现。文档包含详细信息和示例。
moz_task 包装了 XPCOM 的线程函数，以便轻松安全地编写线程代码。它有用于获取和创建线程、调度异步可运行对象以及线程安全句柄的帮助程序。
storage 是 mozStorage 的接口，我们的 SQLite 包装器。它可以包装现有的存储连接，并准备和执行语句。此 crate 包装了同步连接 API，并允许您通过 moz_task 异步执行语句。
storage_variant 用于处理变体。它还提供了一个 HashPropertyBag 类型，该类型对于通过 XPCOM 将哈希映射传递到 JS 很有用。

不幸的是，尚未生成和托管 mozilla-central 中 crate 的 rustdocs。因此，上面显示的 crate 链接尽可能链接到包含相关 rustdocs 源代码的文件。但是，您可以使用上面描述的 cargo doc 命令在本地生成文档。