docs/writing-rust-code/basics.md

   1 # Basics
   2
   3 ## Formatting Rust code
   4
   5 To format all the Rust code within a directory `$DIR`, run:
   6 ```
   7 ./mach lint -l rustfmt --fix $DIR
   8 ```
   9
  10 ## Using Cargo
  11
  12 Many Cargo commands can be run on individual crates. Change into the directory
  13 containing the crate's `Cargo.toml` file, and then run the command with
  14 `MOZ_TOPOBJDIR` set appropriately. For example, to generate and view rustdocs
  15 for the `xpcom` crate, run these commands:
  16
  17 ```
  18 cd xpcom/rust/xpcom
  19 MOZ_TOPOBJDIR=$OBJDIR cargo doc
  20 cd -
  21 firefox target/doc/xpcom/index.html
  22 ```
  23 where `$OBJDIR` is the path to the object directory.
  24
  25 ## Using static prefs
  26
  27 Static boolean/integer prefs can be easily accessed from Rust code. Add a
  28 `rust: true` field to the pref definition in
  29 [modules/libpref/init/StaticPrefList.yaml](https://searchfox.org/mozilla-central/source/modules/libpref/init/StaticPrefList.yaml),
  30 like this:
  31 ```yaml
  32 - name: my.lucky.pref
  33   type: RelaxedAtomicBool
  34   value: true
  35   mirror: always
  36   rust: true
  37 ```
  38 The pref can then be accessed via the `pref!` macro, like this:
  39 ```
  40 let my_lucky_pref = static_prefs::pref!("my.lucky.pref");
  41 ```
  42
  43 ## Helper crates
  44
  45 The following in-tree helper crates provide idiomatic support for some common patterns.
  46 - [nserror](https://searchfox.org/mozilla-central/source/xpcom/rust/nserror/src/lib.rs)
  47 reflects `nsresult` codes into Rust.
  48 - [nsstring](https://searchfox.org/mozilla-central/source/xpcom/rust/nsstring/src/lib.rs)
  49   exposes bindings for XPCOM string types. You can use the same `ns{A,C}String`
  50   types as C++ for owned strings and pass them back and forth over the
  51   boundary. There is also `ns{A,C}Str` for dependent or borrowed strings.
  52 - [xpcom](https://searchfox.org/mozilla-central/source/xpcom/rust/xpcom/src)
  53   provides multiple building blocks for a component's implementation.
  54   - The `RefPtr` type is for managing reference-counted pointers.
  55   - XPCOM service getters are generated by
  56     [xpcom/build/Services.py](https://searchfox.org/mozilla-central/source/xpcom/build/Services.py)
  57     and can be called like this:
  58     ```
  59     let pref_service = xpcom::services::get_PrefService();
  60     ```
  61   - There is also a `get_service` function that works like `do_GetService` in
  62     C++, as an alternative.
  63   - A set of `derive` macros help with declaring interface implementations. The
  64     [docs](https://searchfox.org/mozilla-central/source/xpcom/rust/xpcom/xpcom_macros/src/lib.rs)
  65     have details and examples.
  66 - [moz_task](https://searchfox.org/mozilla-central/source/xpcom/rust/moz_task/src/lib.rs)
  67   wraps XPCOM's threading functions in order to make it easy and safe to write
  68   threaded code. It has helpers for getting and creating threads, dispatching
  69   async runnables, and thread-safe handles.
  70 - [storage](https://searchfox.org/mozilla-central/source/storage/rust/src/lib.rs)
  71   is an interface to mozStorage, our wrapper for SQLite. It can wrap an
  72   existing storage connection, and prepare and execute statements. This crate
  73   wraps the synchronous connection API, and lets you execute statements
  74   asynchronously via `moz_task`.
  75 - [storage_variant](https://searchfox.org/mozilla-central/source/storage/variant/src/lib.rs)
  76   is for working with variants. It also provides a `HashPropertyBag` type
  77   that's useful for passing hash maps over XPCOM to JS.
  78
  79 Unfortunately, rustdocs are [not yet generated and
  80 hosted](https://bugzilla.mozilla.org/show_bug.cgi?id=1428139) for crates within
  81 mozilla-central. Therefore, the crate links shown above link to files
  82 containing the relevant rustdocs source where possible. However, you can
  83 generate docs locally using the `cargo doc` command described above.