Using XPCOM within a Rust component

XPCOM (Cross-Platform Component Object Model) is Mozilla’s compatibility module to allow for cross-platform code across all the different programming languages used in the Firefox and Thunderbird code bases. If you aren’t already familiar with it, the XPCOM documentation on the Firefox source docs website is a good starting point.

XPCOM can be used in Rust via the xpcom crate which can be accessed from the default Cargo workspace within Thunderbird. If you haven’t already done so, make sure to familiarize yourself with including new Rust code in the workspace and getting Thunderbird to build it by following Adding a Rust crate to Thunderbird.

A few internal crates are provided to ease writing and using XPCOM-based objects:

• xpcom (xpcom/rust/xpcom) generates Rust types for all interfaces available through XPCOM, provides a decorator to associate a Rust struct with an XPCOM interface, and provides helper functions, macros, traits and structs for handling XPCOM objects.

• nserror (xpcom/rust/nserror) provides the nsresult enum used by XPCOM objects’ methods.

• nsstring (xpcom/rust/nsstring) provides the string types (nsACString, nsCString, etc.) which map with the corresponding types in XPCOM interface definitions.

• moz_task (xpcom/rust/moz_task) provides traits and utility functions to execute asynchronous Rust code on Firefox/Thunderbird’s thread pools.

• Implementing an XPCOM interface in Rust
  • Implementing the interface in a struct
  • Using XPCOM-compatible types
  • Exposing the method as XPCOM
  • Writing a constructor for the struct
  • Registering the XPCOM component
• Instantiating and using objects through XPCOM in Rust
  • The xpcom crate
  • References on new instances or existing services
  • Calling methods on XPCOM objects
    • Handling output with getter_addrefs
    • Mapping return values of XPCOM methods
  • Casting between XPCOM interfaces

Build the Cargo documentation for internal crates

The documentation for most internal crates is only available as in-code documentation (from which HTML documentation can usually be generated through cargo doc).

In order to generate documentation for a crate depending on internal code, cargo doc needs to run with a special BUILDCONFIG_RS environment variable set. The value for this environment variable is the path to the buildconfig.rs file within the build directory (obj-*). In most cases, this file will be located at obj-[...]/build/rust/mozbuild/buildconfig.rs.

Note

cargo doc will generate HTML documentation in comm/rust/target/doc.

Internal crates will only be included in the generated documentation if cargo doc is ran from within a crate listing them as its dependencies.