Compiling FIDL

Prerequisites

This tutorial builds on the Compiling FIDL tutorial. For more information on other FIDL tutorials, see the Overview.

Overview

This tutorial details how to include the HLCPP FIDL bindings into your code by creating a unit test that you can use as a "playground" for exploring the HLCPP bindings.

This document covers how to complete the following tasks:

Write a C++ host test.
Add the HLCPP bindings of a FIDL library as a build dependency.
Include the HLCPP bindings into your C++ code.
Inspect and use the generated bindings code.

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

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

Write a C++ host test

Add a gtest stub to examples/fidl/hlcpp/unittests/main.cc:

#include <gtest/gtest.h>

namespace {

} // namespace

Define a test and then create a dependency on the test through the $host_toolchain. To do this, add the following to examples/fidl/hlcpp/unittests/BUILD.gn:

import("//build/test.gni")
group("unittests") {
  testonly = true
  deps = [ ":example-cpp-host-test($host_toolchain)" ]
}


test("example-cpp-host-test") {
  sources = [ "main.cc" ]
  deps = [ "//src/lib/fxl/test:gtest_main" ]
}

Add the test suite to your configuration:

fx set product.board --with //examples/fidl/hlcpp/unittests

Run the empty test suite:
```
fx test -vo example-cpp-host-test
```
You should see test output indicating that zero tests have run, since no tests have been added yet.

Add the HLCPP FIDL bindings as a dependency

Add a dependency on the HLCPP bindings by referencing the FIDL target directly. The new test target should look like:

test("example-cpp-host-test") {
  sources = [ "main.cc" ]
  deps = [
    "//examples/fidl/fuchsia.examples:fuchsia.examples_hlcpp",
    "//src/lib/fxl/test:gtest_main",
  ]
}

(Optional) To view the newly generated bindings:

Rebuild using fx build.
Change to the generated files directory: out/default/fidling/gen/examples/fidl/fuchsia.examples/fuchsia/examples, where the generated files are located. You may need to change out/default if you have set a different build output directory. You can check your build output directory with fx get-build-dir.

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

Include the HLCPP bindings in your C++ code

To include the bindings, add the following include statement to the top of examples/fidl/hlcpp/unittests/main.cc

#include <fuchsia/examples/cpp/fidl.h>

Inspect and use the generated bindings code

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

To get started, you can also use some example code. You can add this inside the anonymous namespace in main.cc:

TEST(FidlExamples, Bits) {
  auto flags = fuchsia::examples::FileMode::READ | fuchsia::examples::FileMode::WRITE;
  ASSERT_EQ(static_cast<uint16_t>(flags), 0b11);
  flags |= fuchsia::examples::FileMode::EXECUTE;
  ASSERT_EQ(flags, fuchsia::examples::FileModeMask);
}

TEST(FidlExamples, Enums) {
  ASSERT_EQ(static_cast<uint32_t>(fuchsia::examples::LocationType::MUSEUM), 1u);
}

TEST(FidlExamples, Structs) {
  fuchsia::examples::Color default_color;
  ASSERT_EQ(default_color.id, 0u);
  ASSERT_EQ(default_color.name, "red");

  fuchsia::examples::Color blue = {1, "blue"};
  ASSERT_EQ(blue.id, 1u);
}

TEST(FidlExamples, Unions) {
  auto int_val = fuchsia::examples::JsonValue::WithIntValue(1);
  ASSERT_EQ(int_val.Which(), fuchsia::examples::JsonValue::Tag::kIntValue);
  ASSERT_TRUE(int_val.is_int_value());

  auto str_val = fuchsia::examples::JsonValue::WithStringValue("1");
  ASSERT_EQ(str_val.Which(), fuchsia::examples::JsonValue::Tag::kStringValue);
  ASSERT_TRUE(str_val.is_string_value());

  fuchsia::examples::JsonValuePtr other_int_val = std::make_unique<fuchsia::examples::JsonValue>();
  other_int_val->set_int_value(5);
  ASSERT_EQ(other_int_val->int_value(), 5);
}

TEST(FidlExamples, Tables) {
  fuchsia::examples::User user;
  ASSERT_FALSE(user.has_age());
  user.set_age(100);
  *user.mutable_age() += 100;
  ASSERT_EQ(user.age(), 200);
  user.clear_age();
  ASSERT_TRUE(user.IsEmpty());
}

To rebuild and rerun the tests, run:

fx test -vo example-cpp-host-test