| |
| # FIDL Rust Crates |
| |
| FIDL is the primary mechanism for structured IPC within Fuchsia. The easiest |
| way to use FIDL from Rust is by generating a "FIDL crate" from a FIDL library |
| and then importing it from your Rust library or binary. |
| |
| See [the FIDL Rust bindings](/docs/reference/fidl/bindings/rust-bindings.md) to |
| understand how different FIDL constructs map into their Rust equivalents, and |
| [the FIDL Rust tutorials][tutorials] for examples on using the Rust |
| bindings. |
| |
| ## Build Instructions {#build} |
| |
| When a [GN `fidl` rule](/build/fidl/fidl.gni) is defined for a FIDL library, |
| a corresponding FIDL Rust crate is automatically generated under |
| the original target name appended with `_rust`. Transitive dependencies on |
| other FIDL libraries are resolved automatically. |
| For example, given the declaration: |
| |
| ```gn |
| # //src/tictactoe/BUILD.gn |
| |
| fidl("games.tictactoe") { ... } |
| ``` |
| |
| The FIDL crate target is |
| `//src/tictactoe:games.tictactoe_rust`. To use the FIDL crate, |
| add the target to the `deps` field of the |
| [`rustc_*` build rule](/docs/development/languages/rust/README.md#build) |
| for your Rust crate. For example: |
| |
| ```gn |
| rustc_binary("tictactoe") { |
| # ... |
| deps = ["//src/tictactoe:games.tictactoe_rust"] |
| } |
| ``` |
| |
| The Rust crate will be named `fidl_games_tictactoe` and its items can now be |
| imported: |
| |
| ```rust |
| use fidl_games_tictactoe::BOARD_SIZE; |
| ``` |
| |
| In the Fuchsia tree, frequently used FIDL crates are often aliased to |
| a shorter name for brevity, like so: |
| |
| ```rust |
| use fidl_fuchsia_io as fio; |
| use fidl_fuchsia_data as fdata; |
| ``` |
| |
| ## Generated Documentation {#documentation} |
| |
| Documentation in HTML format can be automatically |
| generated for a FIDL crate using the `fx rustdoc` command. For example: |
| |
| ```bash |
| fx rustdoc //src/tictactoe:games.tictactoe_rust --open |
| ``` |
| |
| FIDL crates in the public Fuchsia source tree are published in the |
| [Fuchsia Rust API reference](https://fuchsia-docs.firebaseapp.com/rust/). |
| |
| ## Generated Rust Code {#code} |
| |
| To manually inspect the generated Rust code for a FIDL crate, the Rust |
| source files are available under the `BUILD_DIR/fidling/gen` (refer to the |
| [Generated code guide][generated-code] for an example). Note that |
| the FIDL crate must first have been built (e.g. using `fx build`). |
| |
| <!-- xrefs --> |
| [generated-code]: /docs/development/languages/fidl/guides/generated-code.md#rust |
| [tutorials]: /docs/development/languages/fidl/tutorials/rust |