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

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

2. Make sure this repository has the required submodules:

   ```sh
   git submodule update --recursive --init
   ```

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

4. Ensure that there are Fuchsia SSH keys in your host machine. You will need
   them for running the Fuchsia emulator.

   ```sh
    [[ -f "${HOME}/.ssh/fuchsia_ed25519" ]] || ssh-keygen -P "" -t ed25519 -f "${HOME}/.ssh/fuchsia_ed25519" -C "${USER}@$(hostname -f) Shared SSH Key for Fuchsia"

    [[ -f "${HOME}/.ssh/fuchsia_authorized_keys" ]] || ssh-keygen -y -f "${HOME}/.ssh/fuchsia_ed25519" > "${HOME}/.ssh/fuchsia_authorized_keys"
   ```

## Build and package the sample

Now the repository is ready to build the sample.

1. Fetch an emulator image:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/tools/ffx product-bundle get workstation_eng.qemu-x64
   ```

2. 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
   
   ```
3. (optional) Watch the device log in a separate window:

   ```sh
   $FUCHSIA_EMBEDDER_DIR/tools/ffx log
   ```

4. Run an example app:

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

**TODO(akbiggs): The app occasionally gets stuck on a loading screen
instead of rendering. Re-running the app usually fixes it. We need to
fix this.**

## Syncing engine artifacts

Occasionally you will need to update the Flutter Engine artifacts (embedder.h and
libengine_flutter.so) that are used by the embedder to run Flutter apps. A script
is provided for this workflow.

### Requirements

1. You will
   [need to get the Flutter Engine source code](https://github.com/flutter/flutter/wiki/Setting-up-the-Engine-development-environment).
   **Note that this is not just cloning https://github.com/flutter/engine.**
2. Set `$ENGINE_DIR` to the `src` folder of your Flutter Engine checkout location,
   for example `~/engine/src`.
3. `$FUCHSIA_EMBEDDER_DIR` should be set to your flutter-embedder.git checkout
   location, for example `~/flutter-embedder`.
4. `$DEPOT_TOOLS` should be set to your
    [`depot_tools`](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html#_setting_up)
    location, for example `~/depot_tools`.
5. You will need to `git stash` or `git commit` any local changes to the Flutter
   Engine or the script will fail.

### Running the script

You can run the script with a `flutter/engine` Git commit to sync the Engine artifacts to
that revision.

```sh
$FUCHSIA_EMBEDDER_DIR/scripts/sync_engine_artifacts_to_revision.sh <ENGINE_COMMIT_SHA>
```

A common workflow is to sync your Engine commit to the Flutter tool in this repository,
for example when updating the Flutter tool to a new version. To do this:

```sh
$FUCHSIA_EMBEDDER_DIR/scripts/sync_engine_artifacts_to_revision.sh $(cat $FUCHSIA_EMBEDDER_DIR/third_party/dart-pkg/internal/flutter/flutter/bin/internal/engine.version)
```