Prerequisites
This tutorial expects that you have completed the Getting Started
guide and are able to build and run Fuchsia (whether using fx qemu
or on actual
hardware). You should be familiar with running components on Fuchsia using
fx serve
and fx shell run
, which are covered in Run an example component.
This tutorial is the first of the sequence of FIDL tutorials listed in the overview.
Overview
In this tutorial, we will define a FIDL library fuchsia.examples
. Defining the
FIDL library lets us compile the .fidl
files using fx build
and check for any errors.
It also creates targets that can be included to depend on the bindings for the
new library. The bindings tutorials, as well as the prerequisites for this tutorial are
listed in the FIDL tutorials overview.
Define the FIDL library
The example code for this tutorial is in //examples/fidl/fuchsia.examples.
We've chosen the directory name to match the library name, which is the
convention taken by the libraries defined in the Fuchsia IDK in
//sdk/fidl
.
We can define some examples of the various FIDL language features in
examples/fidl/fuchsia.examples/types.test.fidl
:
library fuchsia.examples;
const uint8 BOARD_SIZE = 9;
const string NAME = "Tic-Tac-Toe";
bits FileMode : uint16 {
READ = 0b001;
WRITE = 0b010;
EXECUTE = 0b100;
};
enum LocationType {
MUSEUM = 1;
AIRPORT = 2;
RESTAURANT = 3;
};
struct Color {
uint32 id;
string:MAX_STRING_LENGTH name = "red";
};
union JsonValue {
1: reserved;
2: int32 int_value;
3: string:MAX_STRING_LENGTH string_value;
};
table User {
1: reserved;
2: uint8 age;
3: string:MAX_STRING_LENGTH name;
};
struct GameState {
};
protocol TicTacToe {
StartGame(bool start_first);
MakeMove(uint8 row, uint8 col) -> (bool success, GameState? new_state);
-> OnOpponentMove(GameState new_state);
};
and also add a protocol to examples/fidl/fuchsia.examples/echo.test.fidl
:
// Copyright 2020 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 fuchsia.examples;
const uint64 MAX_STRING_LENGTH = 32;
[Discoverable]
protocol Echo {
EchoString(string:MAX_STRING_LENGTH value) -> (string:MAX_STRING_LENGTH response);
SendString(string:MAX_STRING_LENGTH value);
-> OnString(string:MAX_STRING_LENGTH response);
};
[Discoverable]
protocol EchoLauncher {
GetEcho(string:MAX_STRING_LENGTH echo_prefix) -> (Echo response);
GetEchoPipelined(string:MAX_STRING_LENGTH echo_prefix, request<Echo> request);
};
service EchoService {
Echo regular_echo;
Echo reversed_echo;
};
The test.fidl
extension is used instead of just .fidl
, since
exemptions to certain requirements like linting or API review are applied to
test.fidl
files. You should use .fidl
when writing your own FIDL files.
Create a GN target for the FIDL library
Now we can define a target for our FIDL library that other code can depend on:
# Copyright 2020 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 the fidl GN template.
import("//build/fidl/fidl.gni")
# Define a target for our FIDL library by passing it the FIDL source files
# that make up the library.
fidl("fuchsia.examples") {
sources = [
"echo.test.fidl",
"types.test.fidl",
]
fuzzers = [
{
protocol = "fuchsia.examples.Echo"
},
]
}
The fuzzers = [...]
line is only needed to enable fuzzing of protocols
from the library (see FIDL fuzzing), and can otherwise be
omitted.
The bindings tutorials can use the bindings for our FIDL library
by depending on targets generated by the GN fidl
template.
Compile the FIDL library
You can build the .fidl
files and check for syntax errors by including the
target in your build config:
fx set core.x64 --with //examples/fidl/fuchsia.examples
Then run fx build examples/fidl/fuchsia.examples
.