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

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 dependency 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 = "2021"
     sources = [ "src/main.rs" ]
   }
   
   group("fidl_crates") {
      testonly = true
      deps = [ ":fidl_crates_bin($host_toolchain)" ]
   }
   

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.

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 _rust.

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 = "2021"
  deps = [ "//examples/fidl/fuchsia.examples:fuchsia.examples_rust" ]

  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.

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

Using the FIDL Rust crate in your project

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:

rustc_binary("fidl_crates_bin") {
  edition = "2021"
  test_deps = [ "//examples/fidl/fuchsia.examples:fuchsia.examples_rust" ]
  with_unit_tests = true

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

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

group("fidl_crates") {
  testonly = true
  deps = [
    ":fidl_crates_bin($host_toolchain)",
    ":fidl_crates_bin_test($host_toolchain)",
  ]
}

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:

    use fidl_fuchsia_examples as fex;

Use the generated bindings code

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:

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), ..Default::default() };
println!("{:?}", user);
assert!(user.age.is_some());

To rebuild and rerun the tests, run:

fx test -vo fidl_crates_bin_test