docs/development/languages/fidl/tutorials/fidl.md

# Creating a FIDL library

## Prerequisites

This tutorial expects that you have completed the [Getting Started][getting-started]
guide and are able to build and run Fuchsia (using [FEMU][femu] or a physical device).
You should be familiar with running components on Fuchsia, which is covered in
[Run an example component][run-examples]. This tutorial is the first of the
sequence of FIDL tutorials listed in the [overview][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][overview].

## Define the FIDL library

The example code for this tutorial is in
[//examples/fidl/fuchsia.examples](/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`][sdk] such as `//sdk/fidl/fuchsia.url` or `//sdk/fidl/fuchsia.ui.text`.

FIDL file names use the `.fidl` extension. Analogous 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.

The following are some examples of various FIDL language features as defined in
`//examples/fidl/fuchsia.examples/types.test.fidl`:

```fidl
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="lib" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="consts" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="bits" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="enums" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="structs" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="unions" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="tables" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="protocols-preface" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/types.test.fidl" region_tag="protocols" %}
```

and also add a protocol to `examples/fidl/fuchsia.examples/echo.test.fidl`:

```fidl
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/echo.test.fidl" %}
```

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:

```gn
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/fuchsia.examples/BUILD.gn" %}
```

The `fuzzers = [...]` line is only needed to enable fuzzing of protocols
from the library (see [FIDL fuzzing][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][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`.

Note: If you are rewriting the FIDL files yourself, don't forget to add the
Fuchsia copyright notice at the top of each file.

<!-- xrefs -->
[sdk]: /sdk/fidl
[fidl-template]: /build/fidl/fidl.gni
[overview]: /docs/development/languages/fidl/tutorials/overview.md
[femu]: /docs/get-started/set_up_femu.md
[getting-started]: /docs/get-started/README.md
[run-examples]: /docs/development/run/run-examples.md
[fidl-fuzzing]: /docs/development/testing/fuzzing/fidl-fuzzing.md