README.md

flutter-embedder.git
=======================================

The Flutter Embedder for Fuchsia is a new in-progress runtime for Flutter apps
on Fuchsia. This runtime is built on top of Flutter's
[embedder platform](https://github.com/flutter/flutter/wiki/Custom-Flutter-Engine-Embedders).

This repository is a work in progress and should be considered
experimental.

## Requirements

If you're using WSL2 (Windows Subsystem for Linux), see
[SETUP_WINDOWS.md](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/SETUP_WINDOWS.md)
first.

1. Set `$FUCHSIA_EMBEDDER_DIR` to your flutter-embedder.git checkout location,
   for example `~/flutter-embedder`.

   ```sh
   export FUCHSIA_EMBEDDER_DIR=$HOME/flutter-embedder
   ```

2. Bootstrap the repository's dependencies:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/scripts/bootstrap.sh
   ```

   This script initializes tools (including `bazel` and `ffx`), installs some Git
   hooks and downloads the `workstation_eng.qemu-x64` product bundle, which you can
   use to run the examples below.

## Run an example app

1. Start the emulator.

   If running in a graphical environment:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/tools/ffx emu start workstation_eng.qemu-x64
   ```

   If running in a terminal environment:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/tools/ffx emu start --headless workstation_eng.qemu-x64
   ```

   The workflow below also supports
   [Fuchsia builds from source](https://fuchsia.dev/fuchsia-src/get-started/get_fuchsia_source)
   that are within Fuchsia's SDK compatibility window (six weeks).

2. Set the default target in ffx to be `fuchsia-emulator`:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/tools/ffx target default set fuchsia-emulator
   ```

3. Run an example component:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter
   ```

   - To watch logs for the example component, run:

     ```sh
     $FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter --log
     ```

     If you want to watch all logs, run `$FUCHSIA_EMBEDDER_DIR/tools/ffx log` in a separate terminal.

   - To watch FIDL calls for the example component, run:

     ```sh
     $FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter --fidl
     ```

     Caveats:

      - `--fidl` currently requires setting `$FUCHSIA_DIR` to a
      [Fuchsia source checkout](https://fuchsia.dev/fuchsia-src/get-started/get_fuchsia_source)
      with a build in `$FUCHSIA_DIR/out/default`. This directory is only
      used to read IR files for FIDL, you can still use the
      `workstation_eng.qemu-x64` product bundle with `--fidl`.

      - `--fidl` attaches after the component has been run, so it does not pick up
      FIDL calls made when the component starts.

   - To attach a debugger to the example component, see
   [_`debugging.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/debugging.md)

     **TODO(akbiggs): Work with Bazel SDK team to get proper support for `--fidl`.**

## Making Flutter Engine changes

Running the Flutter app is handled by the Flutter Engine's
[embedder platform code](https://github.com/flutter/engine/tree/main/shell/platform/embedder).
This code is compiled into a shared library called `libflutter_engine.so`,
which we can interact with using the `embedder.h` header.

If you need to make changes to this Flutter Engine code (for example for
testing a new API in `embedder.h` with this embedder) see
[_`making_engine_changes.md`_ for instructions](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/making_engine_changes.md).
This isn't required for changes to only flutter-embedder.git's source code.

## Uploading changes for review.

See [_`git_workflow.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/git_workflow.md).