## Prerequisites

In this tutorial, you will be using the `fuchsia.examples` FIDL library from the
[Creating a FIDL library](https://fuchsia.dev/docs/development/languages/fidl/tutorials/fidl) tutorial. The code for this FIDL library
is available in [//examples/fidl/fuchsia.examples](https://cs.opensource.google/fuchsia/fuchsia/+/main:/examples/fidl/fuchsia.examples/echo.test.fidl). 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](https://fuchsia.dev/fuchsia-src/development/languages/fidl/tutorials/rust/basics/using-fidl.md.txt#hello-world).
- [Add the Rust bindings of a FIDL library as a build
  dependency](https://fuchsia.dev/fuchsia-src/development/languages/fidl/tutorials/rust/basics/using-fidl#add-dependency).
- [Import the Rust bindings crate into your code](https://fuchsia.dev/fuchsia-src/development/languages/fidl/tutorials/rust/basics/using-fidl.md.txt#include-rust-bindings).
- [Inspect and use the generated bindings
  code](https://fuchsia.dev/fuchsia-src/development/languages/fidl/tutorials/rust/basics/using-fidl#inspect-user-generated-bindings).

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:

```rust
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`:

   ```rust
   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 = "2024"
         sources = [ "src/main.rs" ]
       }

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

   > [!NOTE]
   > **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 explicitly in the `rustc_binary` declaration (e.g. `source_root = "hello_world.rs"`).

3. Include example in the build

   ```rust
   fx set core.x64 --with //examples/fidl/rust/fidl_crates
   ```
4. Build the example

   ```rust
   fx build
   ```
5. Run the binary

   ```rust
   out/default/host_x64/fidl_crates_bin
   ```

   You should see the hello world message printed.

   > [!NOTE]
   > **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

For each FIDL library declaration, including the one in [Compiling FIDL](https://fuchsia.dev/docs/development/languages/fidl/tutorials/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 = "2024"
      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`.

> [!NOTE]
> **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](https://fuchsia.dev/docs/development/languages/fidl/guides/generated-code#rust).

## 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:

```rust
#[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 = "2024"
      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:

```rust
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:

```rust
    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](https://fuchsia.dev/docs/reference/fidl/bindings/rust-bindings).

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

```rust
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:

```rust
fx test -vo fidl_crates_bin_test
```
[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/development/languages/fidl/tutorials/rust/basics/using-fidl.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/development/languages/fidl/tutorials/rust/basics/using-fidl.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/development/languages/fidl/tutorials/rust/basics/using-fidl.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/development/languages/fidl/tutorials/rust/basics/using-fidl.md "Edit the source code of this page")