Creating a FIDL library

Prerequisites

This tutorial expects that you have completed the getting started guide and are able to build and run Fuchsia. You should be familiar with running components on Fuchsia, which is covered in run an example component.

Overview

In this tutorial, you will define and build the FIDL library examples.keyvaluestore.baseline. After you're done, you'll know how to author a FIDL file, set up necessary GN rules, and build FIDL bindings.

The full source for this tutorial can be found at //examples/fidl/new/key_value_store/baseline/fidl/

Define the FIDL library

First, create a directory for this tutorial by running the following command from your fuchsia checkout:

mkdir -p vendor/fidl-tutorials/building-fidl

Create a new file, key_value_store.test.fidl:

touch vendor/fidl-tutorials/building-fidl/key_value_store.test.fidl

FIDL file names use the .fidl extension. Similar to C header files, FIDL files define data types and declare functional interfaces. These declarations are used in conjunction with FIDL-specific data types to communicate between FIDL endpoints.

Add the following FIDL code to key_value_store.test.fidl:

// Copyright 2022 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library examples.keyvaluestore.baseline;

/// An item in the store. The key must match the regex `^[A-z][A-z0-9_\.\/]{2,62}[A-z0-9]$`. That
/// is, it must start with a letter, end with a letter or number, contain only letters, numbers,
/// periods, and slashes, and be between 4 and 64 characters long.
type Item = struct {
    key string:128;
    value vector<byte>:64000;
};

/// An enumeration of things that may go wrong when trying to write a value to our store.
type WriteError = flexible enum {
    UNKNOWN = 0;
    INVALID_KEY = 1;
    INVALID_VALUE = 2;
    ALREADY_EXISTS = 3;
};

/// A very basic key-value store - so basic, in fact, that one may only write to it, never read!
@discoverable
open protocol Store {
    /// Writes an item to the store.
    flexible WriteItem(struct {
        attempt Item;
    }) -> () error WriteError;
};

This FIDL defines an Item type to represent items in the store, a WriteError enum to list known errors for writes, and a Store protocol with one method: WriteItem. As defined, this library can only write values into a store, but in the key-value store example series, you'll augment this library to support nested stores, reading values, and other features.

Create a GN target for the FIDL library

Now that you've defined your FIDL, you need to create a gn target that other code can depend on.

Create a new file, BUILD.gn:

touch vendor/fidl-tutorials/building-fidl/BUILD.gn

and add the following build rules:

# Copyright 2022 The Fuchsia Authors. All rights reserved.
# Use of this source code is governed by a BSD-style license that can be
# found in the LICENSE file.

import("//build/fidl/fidl.gni")

# Builds the FIDL library into a set of language specific bindings. Bindings for a given language
# may be imported by depending on this target, followed by a language-specific underscore:
#
#   ":examples.keyvaluestore.baseline_rust"
#   ":examples.keyvaluestore.baseline_cpp_wire"
#   ...and so on
#
fidl("examples.keyvaluestore.baseline") {
  sources = [ "key_value_store.test.fidl" ]
  excluded_checks = [ "wrong-prefix-for-platform-source-library" ]
}

The gn template fidl("examples.keyvaluestore.baseline") creates the necessary targets to use this library from other code.

Compile the FIDL library

To build your new FIDL library, run the following fx set command:

fx set core.x64\
  --with //vendor/fidl-tutorials/building-fidl:examples.keyvaluestore.baseline_rust\
  --with //vendor/fidl-tutorials/building-fidl:examples.keyvaluestore.baseline_cpp

This command configures fx build to generate the rust and cpp bindings.

Next, build the code:

fx build

Explore the generated bindings

Now that the code is built, you can explore the generated code for your bindings. To see the generated code, browse the following directories:

binding type	directory
rust	//out/default/fidling/gen/vendor/fidl-tutorials/building-fidl/examples.keyvaluestore.baseline/rust/
new c++	//out/default/fidling/gen/vendor/fidl-tutorials/building-fidl/examples.keyvaluestore.baseline/cpp/fidl/examples.keyvaluestore.baseline/cpp/

See generated code for more details.

Next steps

Now that you've finished this tutorial, you're ready to explore the full key-value store example series.