| 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 |
| |
| This embedder can currently only be built on Linux, not Mac or Windows (native). |
| |
| 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. Clone this repository. |
| |
| ```sh |
| git clone https://fuchsia.googlesource.com/flutter-embedder |
| ``` |
| |
| 2. Set `$FUCHSIA_EMBEDDER_DIR` to your flutter-embedder.git checkout location, |
| for example `~/flutter-embedder`. |
| |
| ```sh |
| export FUCHSIA_EMBEDDER_DIR=$HOME/flutter-embedder |
| ``` |
| |
| 3. 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 |
| ``` |
| |
| If you want to use your own build of Fuchsia instead of a prebuilt image, see |
| [_`testing_fuchsia_sdk_changes.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md). |
| |
| 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](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/src/examples/README.md): |
| |
| ```sh |
| $FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter |
| ``` |
| |
| This can also be done from VSCode by following [this guide](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/debugging.md#attaching-a-debugger-from-vscode). |
| |
| - For an arm64 device, run: |
| |
| ```sh |
| $FUCHSIA_EMBEDDER_DIR/scripts/build_and_run_example.sh hello_flutter --cpu arm64 |
| ``` |
| |
| - 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 using a local Fuchsia SDK instead of the prebuilt |
| Fuchsia SDK. See |
| [this guide for setup instructions](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md). |
| |
| - `--fidl` attaches after the component has been run, so it does not pick up |
| FIDL calls made when the component starts. |
| |
| **TODO(akbiggs): Work with Bazel SDK team to get proper support for `--fidl`.** |
| |
| - To attach a debugger to the example component, see |
| [_`debugging.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/debugging.md) |
| |
| ## Uploading changes for review. |
| |
| See [_`git_workflow.md`_](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/git_workflow.md). |
| |
| ## 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. |
| |
| ## Testing Fuchsia SDK changes |
| |
| You may want to test changes to the Fuchsia platform |
| ([`fuchsia.git`](https://fuchsia.googlesource.com/fuchsia)) against the flutter-embedder |
| repository locally (for example, to validate a WIP API using a Flutter component). |
| To do so, see [_`testing_fuchsia_sdk_changes.md`_ for instructions](https://fuchsia.googlesource.com/flutter-embedder/+/refs/heads/main/docs/testing_fuchsia_sdk_changes.md). |
| |
| This isn't required for changes to only flutter-embedder.git's source code (in which case |
| you can follow [_"Run an example app"_](#run-an-example-app)) or changes |
| to only fuchsia.git's non-SDK code (in which case you can run the example component on |
| an emulator from fuchsia.git). It is only necessary if you have an unsubmitted API in |
| the Fuchsia SDK that you want to test in flutter-embedder. |