FIDL Syntax Update

[Felix Zhu]

tl;dr: the FIDL syntax is changing soon. The FIDL team will migrate all existing files and follow up when this is complete. Please familiarize yourself with the new syntax introduced in RFC-0050 in the meantime.

Hi Team,

Over a year later, the FIDL syntax changes accepted as part of RFC-0050 are finally on the horizon. Over the next few weeks we will be transitioning all existing FIDL files into the new syntax with no action required on your part (though you may need to fix merge conflicts for CLs that are in-progress when the FIDL files get converted). Included below is an overview of the migration, a summary of the syntax changes, and a FAQ section. Please feel free to post on the fidl-dev mailing list with any questions.

Migration Overview

Target audience: you write FIDL and want to know which syntax you should use right now. Or, if you are reviewing migration related CLs in a petal and would like more context.

All FIDL files in any given repository can be in three possible states:

Example	Notes
library example; struct Foo {}; …	Starting state, things are in the old syntax
deprecated_syntax; library example; struct Foo {}; …	Transitional state. Old syntax files must be prefixed with deprecated_syntax;. You should continue writing in the old syntax, but add deprecated_syntax; at the top of any new FIDL files.
library example; type Foo = struct {}; …	Migration is complete - everything is in the new syntax. You must use the new syntax at this point.

Syntax Differences

Target audience: you write FIDL and want to learn more about the new syntax.

This section provides a quick overview of major differences. Please refer to RFC-0050 and related RFCs, as well as the grammar for a more comprehensive overview.

Layout Syntax

The definition of new types (structs, enums, bits, tables, unions) follow the new type [Name] = [Definition] format. For example:

Old	New
struct Foo { ... };	type Foo = struct { ... };

Separating Layouts from Constraints

ABI impacting parameters are placed to the left hand side of the “:”; other parameters are placed on the right hand side. For example:

Old	New
vector<T>:5; array<T>:5;	vector<T>:5; array<T,5>;

Types Come Second

Places where previously we would have [Type] [Identifier] we now have [Identifier] [Type]. For example:

Old	New
const uint32 MaxItems = 10;	const MaxItems uint32 = 10;

Anonymous Layouts

Old	New
struct OnlyUsedOnce { ... }; struct Config {   OnlyUsedOnce param; };	type Config = struct {   param struct { ... }; };

Note: support for anonymous layouts will land some time after the migration is complete. This is tracked in fxbug.dev/74683.

source: RFC-0050

Optional

Nullability is now expressed using the `optional` constraint instead of `?`. The exception is for structs - nullable structs are expressed with `box`, in order to show that adding nullability is an ABI breaking change (not just a constraint, but an actual wire format change).

Old	New
MyUnion? MyStruct?	MyUnion:optional box<MyStruct>

Client End and Server End

These types have now been renamed. The protocol is a constraint to reflect that it does not change the ABI.

Old	New
MyProtocol request<MyProtocol>?	client_end:MyProtocol server_end:<MyProtocol, optional>

Attribute Syntax

Attributes are now specified with @ instead of square brackets. Also, attributes are by convention snake_case instead of CamelCase.

Old	New
[NoDoc] [Deprecated = "Use Meet instead"] protocol Hangouts { ... };	@no_doc @deprecated("Use Meet instead") protocol Hangouts { ... };

source: RFC-0086

Method Syntax

Old	New
protocol Oven {   StartBake(Temperature temp); }	protocol Oven {   StartBake(struct { temp Temperature; }); }

Note: initially FIDL will only support top level request/response types that are non-empty structs. support for other types will be implemented separately as part of work for RFC-0087 and is tracked by fxbug.dev/76349

source: RFC-0087

Default Flexible

Enums, bits, and tables are by default flexible instead of strict. However, users are encouraged to specify strict or flexible explicitly.

Old	New
union Either { ... }; flexible union Command { ... };	type Either = strict union { ... }; type Command = flexible union { ... };

FAQs

Why are we changing the FIDL syntax?

This consists of a number of improvements that have been grouped together. The motivation section of RFC-0050 provides more details.

What should we do with in-progress CLs during the migration?

If the FIDL files in your repository get updated before you can submit your CL, you will need to rebase and update any of your changes to the new syntax. If you have any particularly large changes, please post on the fidl-dev mailing list and the FIDL team will work to coordinate with you.

[Alex Zaslavsky]

TL:DR: All FIDL files in fuchsia.git have been migrated to the new syntax.  All new FIDL you add going forward should be written in the new syntax as well.

The old FIDL syntax is dead, long live the new FIDL syntax.

The migrated syntax has landed in fuchsia.git.  Documentation will be updated shortly as well.  If you have WIP changes to FIDL files, see the instructions below for how to merge with HEAD successfully.

Writing new FIDL files in the old syntax is strongly discouraged everywhere, and will soon be disabled completely.  All new FIDL files should be written in the new syntax instead.

A number of tooling extensions that support FIDL will be broken for a short time until updated versions can be landed.  These include the VSCode/IntelliJ plugins and Code Search highlighting.

If you encounter any issues that seem to be related to the new syntax migration, please file bugs that CC tq-fidl-...@google.com.

I have a WIP FIDL Change that won't merge now, help!

You'll have to convert each of the FIDL files in your change manually before you rebase onto HEAD, but don't worry, this shouldn't be too difficult.  Each fidl_library GN rule has a directory where it writes its outputs after an fx build.  For example, the output for the FIDL files in sdk/fidl/fuchsia.bluetooth is written to out/default/fidling/gen/sdk/fidl/fuchsia.bluetooth.  Each such output directory contains a .args file, which stores the command line string used to invoke fidlc to generate the library in question.

So, to pass any of your FIDL files through the converter manually, you'll need to:

1. Locate the .args file for the library you wish to convert.

2. Copy the text of that file, add --convert-syntax ~/tmp/some/output/dir to the front, and execute from the command line.

3. Assuming all of your existing FIDL files were valid old syntax FIDL,  copies of all of the FIDL files for this library will be written to ~/tmp/some/output/dir, and may be copied back into your workspace as necessary.

[Shai Barack]

Congratulations on achieving this complex change!