Prerequisites

In this tutorial, you will be using thefuchsia.examples FIDL library from theCreating a FIDL library tutorial. The code for this FIDL libraryis available in//examples/fidl/fuchsia.examples. Take a minute toreview the code before moving on.

Overview

This tutorial details how to use FIDL from Rustby creating a unit test that you can use as a "playground" forexploring 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 builddependency.
• Import the Rust bindings crate into your code.
• Inspect and use the generated bindingscode.

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

rm-rexamples/fidl/rust/fidl_crates/*

Write a "hello world" program

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

   fnmain(){println!("Hello, world!");}

2. Define arustc_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 toexamples/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=truedeps=[":fidl_crates_bin($host_toolchain)"]}

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

3. Include example in the build

   fxsetcore.x64--with//examples/fidl/rust/fidl_crates

4. Build the example

   fxbuild

5. Run the binary

   out/default/host_x64/fidl_crates_bin

   You should see the hello world message printed.

   Note: the directory insideout/default will depend on your machine andconfiguration. For example, if you're running on an ARM machine with ASan,the directory will beout/default/host_arm64-asan instead.

Add the Rust FIDL bindings as a dependency

For each FIDL library declaration, including the one inCompiling FIDL,a FIDL crate containing Rust bindings code for that library is generated under the original targetname appended with_rust.

Add a dependency on the Rust bindings by referencing this generated crate. The newrustc_binarytarget 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 usingfx build.
2. Change to the generated files directory:out/default/fidling/gen/examples/fidl/fuchsia.examples/fuchsia.examples. The generated code is infidl_fuchsia_examples.rs.You may need to changeout/default if you have set a different build outputdirectory. You can check your build output directory withcat .fx-build-dir.

For more information on how to find generated bindings code, seeViewing 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 testmodule and placeholder test:

#[cfg(test)]modtest{#[test]fnfidl_crates_usage(){}}

You then need to build with tests by setting thewith_unit_tests argument:

rustc_binary("fidl_crates_bin") {  edition = "2024"  test_deps = [ "//examples/fidl/fuchsia.examples:fuchsia.examples_rust" ]  with_unit_tests = true  sources = [ "src/main.rs" ]}

This will generate afidl_crates_bin_test target, which should then be addedto the build group:

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

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

usefidl_fuchsia_examplesasfex;

Use the generated bindings code

You can now write some code using the generated bindings code. For moreinformation on the bindings, seeRust Bindings Reference.

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

letflags=fex::FileMode::READ|fex::FileMode::WRITE;println!("{:?}",flags);letfrom_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);letred=fex::Color{id:0u32,name:"red".to_string()};println!("{:?}",red);letint_val=fex::JsonValue::IntValue(1);letstr_val=fex::JsonValue::StringValue("1".to_string());println!("{:?}",int_val);assert_ne!(int_val,str_val);letuser=fex::User{age:Some(20),..Default::default()};println!("{:?}",user);assert!(user.age.is_some());

To rebuild and rerun the tests, run:

fxtest-vofidl_crates_bin_test