using-fidl.md

FIDL Rust crates

Prerequisites

In this tutorial, you will be using the fuchsia.examples FIDL library from the Creating a FIDL library tutorial. The code for this FIDL library is available in //examples/fidl/fuchsia.examples. Take a minute to review the code before moving on.

Overview

This tutorial details how to use FIDL from Rust by creating a unit test that you can use as a "playground" for exploring the Rust bindings.

This document covers how to complete the following tasks:

• Write a "hello world" Rust program.
• Add the Rust bindings of a FIDL library as a build dependency.
• Import the Rust bindings crate into your code.
• Inspect and use the generated bindings code.

The example code is located in your Fuchsia checkout in //examples/fidl/rust/fidl_crates/. If you want to write all the code as you follow this tutorial, you can remove the example code:

rm -r examples/fidl/rust/fidl_crates/*

Write a "hello world" program {#hello-world}

1. Add the main function to examples/fidl/rust/fidl_crates/src/main.rs:

   {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="main" adjust_indentation="auto" %}

2. Define a rustc_binary and then create a depencency on the test through the $host_toolchain, which will build the binary for the host. To do this, add the following to examples/fidl/rust/fidl_crates/BUILD.gn:

   {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/BUILD.gn" region_tag="imports" %}
   
   rustc_binary("fidl_crates_bin") {
     edition = "2018"
     sources = [ "src/main.rs" ]
   }
   
   group("fidl_crates") {
      testonly = true
      deps = [ ":fidl_crates_bin($host_toolchain)" ]
   }

   Note: rustc_binary will look for a src/main.rs file by default as the crate root. It is possible to place the test code in a different file (e.g. hello_world.rs) instead, and then specify the crate root explicity in the rustc_binary declaration (e.g. source_root = "hello_world.rs").

3. Include example in the build

   fx set core.x64 --with //examples/fidl/rust/fidl_crates
   

4. Build the example

   fx build
   

5. Run the binary

   out/default/host_x64/fidl_crates_bin
   

   You should see the hello world message printed.

   Note: the directory inside out/default will depend on your machine and configuration. For example, if you're running on an ARM machine with ASan, the directory will be out/default/host_arm64-asan instead.

Add the Rust FIDL bindings as a dependency {#add-dependency}

For each FIDL library declaration, including the one in Compiling FIDL, a FIDL crate containing Rust bindings code for that library is generated under the original target name appended with -rustc.

Add a dependency on the Rust bindings by referencing this generated crate. The new rustc_binary target should look like:

rustc_binary("fidl_crates_bin") {
  edition = "2018"
  deps = [ "//examples/fidl/fuchsia.examples:fuchsia.examples-rustc" ]

  sources = [ "src/main.rs" ]
}

(Optional) To view the newly generated bindings:

1. Rebuild using fx build.
2. Change to the generated files directory: out/default/fidling/gen/examples/fidl/fuchsia.examples/fuchsia.examples. The generated code is in fidl_fuchsia_examples.rs. You may need to change out/default if you have set a different build output directory. You can check your build output directory with cat .fx-build-dir.

Note: The generated FIDL bindings are part of the build output and are not checked in.

For more information on how to find generated bindings code, see Viewing generated bindings code.

Using the FIDL Rust crate in your project {#include-rust-bindings}

Create a place to play around with the generated FIDL crate by adding a test module and placeholder test:

#[cfg(test)]
mod test {
   #[test]
   fn fidl_crates_usage() {

   }
}

You then need to build with tests by setting the with_unit_tests argument:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/BUILD.gn" region_tag="test" %}

This will generate a fidl_crates_bin_test target, which should then be added to the build group:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/BUILD.gn" region_tag="group" %}

To import the crate, add the following to the top of the tests module. In the Fuchsia tree, FIDL crates are often aliased to shorter names for brevity:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="import" %}

Use the generated bindings code {#inspect-user-generated-bindings}

You can now write some code using the generated bindings code. For more information on the bindings, see Rust Bindings Reference.

To get started, you can also use the example code below. You can add this inside the fidl_crates_usage test:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="bits" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="enums_init" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="structs" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="unions_init" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/rust/fidl_crates/src/main.rs" region_tag="tables_init" adjust_indentation="auto" %}

To rebuild and rerun the tests, run:

fx test -vo fidl_crates_bin_test