Google is committed to advancing racial equity for Black communities. See how.

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:

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

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

Write a "hello world" program

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

    fn main() {
       println!("Hello, world!");
    }
    
  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:

    import("//build/rust/rustc_binary.gni")
    
    
    rustc_binary("fidl_crates_bin") {
      edition = "2018"
      sources = [ "src/main.rs" ]
    }
    
    group("fidl_crates") {
      testonly = true
      deps = [ ":fidl_crates_bin($host_toolchain)" ]
    }
    
  3. Build the file

    fx set core.x64 --with //examples/fidl/rust/fidl_crates
    
  4. Run the binary

    out/default/host_x64/fidl_crates_bin`
    

    You should see the hello world message printed.

Add the Rust FIDL bindings as a 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_test 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. 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.

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

Import the FIDL Rust crate into your project

To import the crate, add the following to the top of the tests module in examples/fidl/rust/fidl_crates/src/main.rs. In the Fuchsia tree, FIDL crates are often aliased to shorter names for brevity.

use fidl_fuchsia_examples as fex;

Use the generated bindings code

You can now write some tests by referring to the generated code. For more information on the bindings, see Rust Bindings Reference.

To get started, you can also use some example code. You can add this inside the tests module:

let flags = fex::FileMode::Read | fex::FileMode::Write;
println!("{:?}", flags);

let from_raw = fex::LocationType::from_primitive(1).expect("Could not create LocationType");
assert_eq!(from_raw, fex::LocationType::Museum);
assert_eq!(fex::LocationType::Restaurant.into_primitive(), 3);

let red = fex::Color { id: 0u32, name: "red".to_string() };
println!("{:?}", red);

let int_val = fex::JsonValue::IntValue(1);
let str_val = fex::JsonValue::StringValue("1".to_string());
println!("{:?}", int_val);
assert_ne!(int_val, str_val);

let user = fex::User { age: Some(20), ..fex::User::empty() };
println!("{:?}", user);
assert!(user.age.is_some());

To rebuild and rerun the tests, run:

fx test -vo fidl_crates_test