Skip to content

Latest commit

 

History

History
147 lines (102 loc) · 5.46 KB

using-fidl.md

File metadata and controls

147 lines (102 loc) · 5.46 KB

FIDL Dart packages

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 use FIDL from Dart by creating a unit test that you can use as a "playground" for exploring the Dart bindings.

This document covers how to complete the following tasks:

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

rm -r examples/fidl/dart/fidl_packages/*

Relative paths in the rest of the tutorial will be relative to this directory.

Write a Dart host test {#write-a-dart-test}

  1. Add a sample test to test/types_test.dart:

    import 'package:test/test.dart';

void main() {
  test('sample', () {
    expect(1 + 1, equals(2));
  });
}

  2. Define a dart_test and then create a depencency on the test through the $host_toolchain. To do this, add the following to BUILD.gn:

    {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/BUILD.gn" region_tag="imports" %}

 dart_test("fidl-example-dart-test") {
   sources = [ "types_test.dart" ]
   deps = [ "//third_party/dart-pkg/pub/test" ]
 }

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/BUILD.gn" region_tag="group" %}

    Note: dart_test will look for source files in the test dir by default, so types_test.dart is specified relative to that directory. A different directory can be used by specifying a value for source_dir.

  3. Create an empty pubspec file at pubspec.yaml:

    {% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/pubspec.yaml" %}

  4. Run the empty test suite:

    fx set core.x64 --with //examples/fidl/dart/fidl_packages
fx test -vo fidl-example-dart-test

    You should see test output for the sample test that was added.

Add the Dart FIDL bindings as a dependency {#add-dependency}

For each FIDL library declaration, including the one in Compiling FIDL, a Dart package containing bindings code for that library is generated under the original target name.

Add a dependency on the Dart bindings by referencing this generated crate. The new dart_test target should look like:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/BUILD.gn" region_tag="test" %}

(Optional) To view the newly generated bindings:

  1. Rebuild using fx build.
  2. Change to the generated files directory: out/default/dartlang/gen/examples/fidl/fuchsia.examples/fuchsia.examples_package. The code is generated into lib/fidl_async.dart and lib/fidl_test.dart. You may need to change out/default if you have set a different build output directory. You can check your build output directory with cat .fx-build-dir.

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

Import the FIDL Dart package into your project {#include-dart-bindings}

To import the package, add the following import statement to the top of the types_test.dart file:

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/test/types_test.dart" region_tag="import" adjust_indentation="auto" %}

In the Fuchsia tree, FIDL package imports are often aliased to fidl_[library] for readability.

Inspect and use the generated bindings code {#inspect-user-generated-bindings}

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

To get started, you can also use some example code. You can add the following tests inside main():

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/test/types_test.dart" region_tag="bits" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/test/types_test.dart" region_tag="enums" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/test/types_test.dart" region_tag="structs" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/test/types_test.dart" region_tag="unions" adjust_indentation="auto" %}

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="examples/fidl/dart/fidl_packages/test/types_test.dart" region_tag="tables" adjust_indentation="auto" %}

To rebuild and rerun the tests, run:

fx test -vo fidl-example-dart-test