fidl_crates.md

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 to understand how different FIDL constructs map into their Rust equivalents, and the FIDL Rust tutorials for examples on using the Rust bindings.

Build Instructions {#build}

When a GN fidl rule is defined for a FIDL library, a correspoding FIDL Rust crate is automatically generated under the original target name appended with -rustc. Transitive dependencies on other FIDL libraries are resolved automatically. For example, given the declaration:

# //src/tictactoe/BUILD.gn

fidl("games.tictactoe") { ... }

The FIDL crate target is //src/tictactoe:games.tictactoe-rustc. To use the FIDL crate, add the target to the deps field of the rustc_* build rule for your Rust crate. For example:

rustc_binary("tictactoe") {
  # ...
  deps = ["//src/tictactoe:games.tictactoe-rustc"]
}

The Rust crate will be named fidl_games_tictactoe and its items can now be imported:

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:

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:

fx rustdoc //src/tictactoe:games.tictactoe-rustc --open

FIDL crates in the public Fuchsia source tree are published in the Fuchsia Rust API reference.

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 for an example). Note that the FIDL crate must first have been built (e.g. using fx build).