blob: 53e851fc151e29e5d55cf58d72916bfce1a85787 [file] [log] [blame] [view]
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.